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源码 目录 结构 

与 NW.js ( 原 node-webkit) 在 技术 上 的 差异 
构建 系统 概览 

构建 步骤 (OSX) 

构建 步骤 (Windows ) 

构建 步 (Linux) 

在 调试 中 使 用 Symbol Server 


Electron 中 文 文档 


来 源 : Electron 中 文 文档 


Electron 常见 问题 


Electron 会 在 什么 时 候 升级 到 最 新 版 本 的 Chrome ? 


通常 来 说 ， 在 稳定 版 的 Chrome 发 布 后 两 周 内 ， 我 们 会 更 新 Electron 内 的 Chrome 版 本 。 


我 们 只 会 使 用 stable 版 本 的 Chrome。 但 如 果 在 beta 或 dev 版 本 中 有 一 个 重要 的 更 新 ， 我 们 
会 把 补丁 应 用 到 现 版 本 的 Chrome 上 。 


Electron 会 在 什么 时 候 升 级 到 最 新 版 本 的 Node.js ? 
我 们 通常 会 在 最 新 版 的 Node.js 发 布 后 一 个 月 左右 将 Electron 更 新 到 这 个 版 本 的 Node.js ° R 
们 通过 这 种 方式 来 避免 新 版 本 的 Node.js 带 来 的 bug (这 种 bug 太 常 见 了 ) © 


Node.js 的 新 特性 通常 是 由 新 版 本 的 V8 带 来 的 。 由 于 Electron 使 用 的 是 Chrome 浏览 器 中 附 
带 的 V8 引擎 ， 所 以 Electron 内 往往 已 经 有 了 部 分 新 版 本 Node.js 才 有 的 办 新 特性 。 


如 何在 两 个 网 页 间 共 至 数据 ? 


在 两 个 网 页 CERRI) 间 共 享 数 据 最 简单 的 方法 是 使 用 浏览 器 中 已 经 实现 的 HTML5 API ? 
比较 好 的 方案 是 用 Storage API’ 1localstorage ， sessionStorage 或 者 IndexedDB ° 


你 还 可 以 用 Electron 内 的 IPC 机制 实现 。 将 数据 存在 主 进程 的 某 个 全 局 变量 中 ， 然 后 在 多 个 
UFZ PLS remote 模块 来 访问 它 


aS 
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global. sharedobject ={ 
someProperty: ‘default value' 


i $- F DONS r } 
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require( "remote').getGlobal('sharedObject').someProperty = 'new value'; 
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console .log(require('remote').getGlobal('sharedObject').someProperty) ; 


为 什么 应 用 的 窗口 、 托 盘 在 一 段 时 间 后 不 见 了 ? 


党 是 因为 用 来 存放 窗口 、 托 盘 的 变量 被 垃圾 收集 了 。 


你 可 以 参考 以 下 两 篇 文章 来 了 解 为 什么 会 遇 到 这 个 问题 。 


。 内 存 管理 
e 变量 作用 域 


如 果 你 只 是 要 一 个 快速 的 修复 方案 ， 你 可 以 用 下 面 的 方式 改变 变量 的 作用 域 ， 防 止 这 个 变量 
被 垃圾 收集 。 


从 


app.on('ready', function() { 
var tray = new Tray('/path/to/icon.png'); 
}) 


BA 


var tray = null; 
app.on('ready', function() { 

tray = new Tray('/path/to/icon.png'); 
t) 


在 Electron 中 ， 我 为 什么 不 能 用 jQuery、 
RequireJS ` Meteor ` Jea a 4 


因为 Electron 在 运行 环境 中 引入 了 Neds ss ， 所 以 在 DOM ie 些 额 外 的 变量 ， 比 如 
module ` exports 和 require 。 这 导致 了 许多 库 不 能 正常 运行 ， 因 为 它们 也 需要 将 同名 的 
量 加 入 运行 环境 中 。 


我 们 可 以 通过 禁用 Node.js 来 解决 这 个 问题 ， 用 如 下 的 方式 : 


// 在 主 进程 中 
var mainWindow = new BrowserWindow( { 
webPreferences: { 
nodeIntegration: false 
} 
}); 


假如 你 依然 需要 使 用 Node.js 和 Electron 提供 的 API， 你 需要 在 引入 那些 库 之 前 将 这 些 变量 
重 命名 ， 比 如 : 


<head> 

<script> 

// 重 命名 Electron 提供 的 require 

window.nodeRequire = require; 

delete window.require; 

delete window.exports; 

delete window.module; 

</script> 

<script type="text/javascript" src="jquery.js"></script> 
</head> 


为 什么 。 require('electron').xxx 的 结果 是 
undefined ? 


在 使 用 Electron 的 提供 的 模块 时 ， 你 可 能 会 遇 到 和 以 下 类 似 的 错误 : 


> require('electron').webFrame.setZoomFactor(1.0); 
Uncaught TypeError: Cannot read property 'setZoomLevel' of undefined 


这 是 因为 你 在 项 目 中 或 者 在 全 局 中 安装 了 npm 上 获取 的 electron 模块 ， 它 把 Electron 的 内 


置 模块 覆 写 了 。 
你 可 以 通 过 以 下 方式 输 出 electron 模块 的 路 径 来 确认 你 是 否 使 用 了 正确 的 模块 。 


console.log(require.resolve('electron')); 


确认 以 下 它 是 不 是 像 下 面 这 样 的 : 


"/path/to/Electron.app/Contents/Resources/atom.asar/renderer/api/lib/exports/electron.js" 
SSS SS SS SS SSS SS ae ee 


假如 输出 的 路 径 类 似 于 node_modules/electron/index.js ， 那 么 你 需要 移 除 或 者 重 命名 npm 
上 的 electron 模块 。 


npm uninstall electron 
npm uninstall -g electron 


如 果 你 依然 遇 到 了 这 个 问题 ， 你 可 能 需要 检查 一 下 拼写 或 者 是 否 在 错误 的 进程 中 调用 了 这 
模块 。 比 如 ， require('electron').app 只 能 在 主 进程 中 使 用 , 然而 


能 
require('electron' ).webFrame 只 能 在 ; 泻 染 进程 中 使 用 © 


支持 的 平台 


以 下 的 平台 是 Electron 目前 支持 的 : 


OS X 


对 于 OS X 系统 仅 有 64 位 的 二 进 制 文档 ， 支 持 的 最 低 版 本 是 OS X 10.8 ° 


Windows 
仅 支 持 Windows 7 及 其 以 后 的 版 本 ， 之 前 的 版 本 中 是 不 能 工作 的 。 


对 于 Windows 提供 x86 和 amd64 (X64) 版 本 的 二 进 制 文件 。 需 要 注意 的 是 ARM 版 本 的 
Windows 目前 尚 不 支持 . 


Linux 


预 编译 的 ia32 ( i686 ) 和 x64 ( amd64 ) 版 本 Electron 二 进 制 文件 都 是 在 Ubuntu 12.04 下 
编译 的 ， arm 版 的 二 进 制 文件 是 在 ARM v7 ( 硬 浮 点 ABI 与 Debian Wheezy 版 本 的 
NEON) 下 完成 的 。 


预 编 译 二 进 制 文 件 是 否 能 够 运行 ， 取 决 于 其 中 是 否 包括 了 编译 平台 链接 的 库 ， 所 以 只 
Ubuntu 12.04 可 以 保证 正常 工作 ， 但 是 以 下 的 平台 也 被 证 实 可 以 运行 Electron 的 预 编译 版 
本 : 

e Ubuntu 12.04 及 更 新 


e Fedora 21 
e Debian 8 


BL Fl eB 


为 了 使 用 Electron 部 署 你 的 应 用 程序 ， 你 存放 应 用 程序 的 文件 夹 需要 叫做 app 并 且 需 要 放 
在 Electron 的 资源 文件 夹 下 (在 OSX 中 是 指 Electron.app/Contents/Resources/ ° Æ Linux 
和 Windows 中 是 指 resources/ ) 就 像 这 样 : 


在 OSX 中: 


electron/Electron.app/Contents/Resources/app/ 
| 一 package. json 
| main.js 


L— index.html 


在 Windows 和 Linux 中 : 


electron/resources/app 
| 一 package. json 
| main.js 


L— index.html 


然后 运行 Electron.app (或 者 Linux 中 的 electron » Windows 中 的 electron.exe ) , # 
着 Electron 就 会 以 你 的 应 用 程序 的 方式 局 动 。 electron 文件 夹 将 被 部 署 并 可 以 分 发 给 最 终 
的 使 用 者 。 


将 你 的 应 用 程序 打包 成 一 个 文件 
除了 通过 拷贝 所 有 的 资源 文件 来 分 发 你 的 应 用 程序 之 外 ， 你 可 以 可 以 通过 打包 你 的 应 用 程序 
为 一 个 asar 库 文件 以 避免 暴露 你 的 源 代码 。 


为 了 使 用 一 个 asar 库 文件 代替 app 文件 夹 ， 你 需要 修改 这 个 库 文件 的 名 字 为 app.asar 
， 然 后 将 其 放 到 Electron 的 资源 文件 夹 下 ， 然 后 Electron 就 会 试图 读 取 这 个 库 文件 并 从 中 局 
动 PTAR: 


在 OSX 中: 


electron/Electron.app/Contents/Resources/ 
L— app.asar 


在 Windows 和 Linux 中 : 


electron/resources/ 
L— app.asar 


更 多 的 细节 请 见 Application packaging. 


更 换 名 称 与 下 载 二 进 制 文件 


在 使 用 Electron 打包 你 的 应 用 程序 之 后 ， 你 可 能 需要 在 分 发 给 用 户 之 前 修改 打包 的 名 字 。 


Windows 


你 可 以 将 electron.exe 改 成 任意 你 喜欢 的 名 字 ， 然 后 可 以 使 用 像 rcedit 编辑 它 的 icon 和 其 
他 信息 。 


OS X 


你 可 以 将 Electron.app 改 成 任意 你 喜欢 的 名 字 ， 然 后 你 也 需要 修改 这 些 文件 中 的 


CFBundleDisplayName °’ CFBundleIdentifier 以 及 cFBundleName 字段 。 这些 文件 如 下 : 


@ cElectron.app/Contents/Info.plist 


@ Electron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist 


你 也 可 以 重 命名 帮助 应 用 程序 以 避免 在 应 用 程序 监视 器 中 显示 Electron Helper ， 但 是 请 确 
保 你 已 经 修改 了 帮助 应 用 的 可 执行 文件 的 名 字 。 


一 个 改过 名 字 的 应 用 程序 的 构造 可 能 是 这 样 的 : 


MyApp.app/Contents 
| 一 Info.plist 
| 一 MacOS/ 
| [一 MyApp 
-一 Frameworks/ 
-一 MyApp Helper EH.app 
| | 一 Info.plist 
| L— MacOS/ 
| L— MyApp Helper EH 
-一 MyApp Helper NP.app 
| | 一 Info.plist 
| L— MacOS/ 
| L— MyApp Helper NP 
— MyApp Helper .app 

| 一 Info.plist 

-一 MacoS/ 

L— MyApp Helper 





Linux 


你 可 以 将 electron 改 成 任意 你 喜欢 的 名 字 。 


通过 重 编译 源 代码 来 更 换 名 称 


通过 修改 产品 名 称 并 重 编译 源 代码 来 更 换 Electron 的 名 称 也 是 可 行 的 。 你 需要 修改 
atom.gyp 文件 并 彻底 重 编译 一 次 。 


grunt 打 包 脚 本 


手动 检查 Electron 代码 并 重 编译 是 很 复杂 蜀 汲 的 ， 因 此 有 一 个 Grunt 任 务 可 以 自动 的 处 理 这 
些 内 容 grunt-build-atom-shell. 


这 个 任务 会 自动 的 处 理 编辑 .gyp 文件 ， 从 源 代码 进行 编译 ， 然 后 重 编译 你 的 应 用 程序 的 本 
地 Node 模块 以 匹配 这 个 新 的 可 执行 文件 的 名 称 。 


Mac App Store 应 用 提交 向 导 


自从 v0.34.0, Electron 就 允许 提交 应 用 包 到 Mac App Store (MAS) . 这 个 向 导 提 供 的 信息 有 : 
如 何 提交 应 用 和 MAS 构建 的 限制 . 


注意 : 从 v0.36.0， 当 应 用 成 为 沙 箱 之 后 ， 会 有 一 个 bug 阻止 GPU 进程 开启 ,所 以 在 这 个 bug 
修复 之 前 ， 建 议 使 用 v0.35.x .更 多 查看 issue #3871. 


注意 : 提交 应 用 到 Mac App Store 需要 参加 Apple Developer Program , 这 需要 花 钱 . 


如 何 提 交 


下 面 步骤 介绍 了 一 个 简单 的 提交 应 用 到 商店 方法 .然而 ， 这 些 步 骤 不 能 保证 你 的 应 用 被 Apple 
接受 ; 你 仍然 需要 阅读 Apple 的 Submitting Your App 关于 如 何 满足 Mac App Store 要 求 的 向 
导 . 


获得 证 书 
为 了 提交 应 用 到 商店 ， 首 先 需要 从 Apple 获得 一 个 证 书 .可 以 遵循 existing guides. 


App 签名 


获得 证 书 之 后 ， 你 可 以 使 用 Application Distribution 打包 你 的 应 用 , 然后 前 往 提 交 你 的 应 用 .这 
个 步骤 基本 上 和 其 他 程序 一 样 ， 但 是 这 key 一 个 个 的 标识 Electron 的 每 个 依赖 . 


首先 ， 你 需要 准备 2 个 授权 文件 . 
child.plist 


<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyL 
<plist version="1.0"> 
<dict> 
<key>com.apple.security.app-sandbox</key> 
<true/> 
<key>com.apple.security.inherit</key> 
<true/> 
</duct> 
</plist> 





parent.plist 


<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyL 
<plist version="1.0"> 
<dict> 
<key>com.apple.security.app-sandbox</key> 
<true/> 
</dict> 
</plist> 


mi 


然后 使 用 下 面 的 脚本 标识 你 的 应 用 : 








#!/bin/bash 


# Name of your app. 

APP="YourApp" 

# The path of you app to sign. 

APP_PATH="/path/to/YouApp.app" 

# The path to the location you want to put the signed package. 
RESULT_PATH="~/Desktop/$APP. pkg" 

# The name of certificates you requested. 

APP_KEY="3rd Party Mac Developer Application: Company Name (APPIDENTITY)" 
INSTALLER_KEY="3rd Party Mac Developer Installer: Company Name (APPIDENTITY)" 





FRAMEWORKS_PATH="$APP_PATH/Contents/Frameworks" 


codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Fram 
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper.a 
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper E 
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper N 
if [ -d "$FRAMEWORKS_PATH/Squirrel.framework/Versions/A" ]; then 
# Signing a non-MAS build. 
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Mantle. fram 
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/ReactiveCoc 
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Squirrel.fr 
fal 
codesign -fs "$APP_KEY" --entitlements parent.plist "$APP_PATH" 


productbuild --component "$APP_PATH" /Applications --sign "$INSTALLER_KEY" "$RESULT_PATH" 





如 果 你 是 OS X 下 的 应 用 沙 箱 使 用 新 手 ， 应 当 仔细 阅读 Apple 的 Enabling App Sandbox 来 有 
一 点 基础 ,然后 向 授权 文件 添加 你 的 应 用 需要 的 许可 keys . 


上 传 你 的 应 用 并 检查 提交 


在 签名 应 用 之 后 ， 可 以 使 用 应 用 Loader #1142) iTunes 链接 处 理 ,确保 在 上 传 之 前 你 已 经 


created a record. 然后 你 能 submit your app for review. 


MAS 74 32 FR 7 


为 了 让 你 的 应 用 沙 箱 满足 所 有 条 件 ， 在 MAS 构建 的 时 候 ， 下 面 的 模块 被 禁用 了 : 


@ crashReporter 


e autoUpdater 


并 且 下 面 的 行为 也 改变 了 : 


一 些 机 子 的 视频 采集 功能 无 效 . 
某 些 特征 不 可 访问 . 
Apps 不 可 识别 DNS 改变 . 


也 由 于 应 用 沙 箱 的 使 用 方法 ， 应 用 可 以 访问 的 资源 被 严格 限制 了 ; 阅读 更 多 信息 App 
Sandboxing . 


Electron 使 用 的 加 密 算 法 


取决 于 你 所 在 地 方 的 国家 和 地 区 ，Mac App Store 或 许 需要 记录 你 应 用 的 加 密 算 法 ,甚至 要 求 
你 提交 一 个 U.S 加 密 注 册 (ERN) 许可 的 复印 件 . 


Electron 使 用 下 列 加 密 算 法 : 


AES - NIST SP 800-38A, NIST SP 800-38D, RFC 3394 
HMAC - FIPS 198-1 

ECDSA - ANS X9.62—2005 

ECDH - ANS X9.63—2001 

HKDF - NIST SP 800-56C 

PBKDF2 - RFC 2898 

RSA - RFC 3447 

SHA - FIPS 180-4 

Blowfish - https://www.schneier.com/cryptography/blowfish/ 
CAST - RFC 2144, RFC 2612 

DES - FIPS 46-3 

DH - RFC 2631 

DSA - ANSI X9.30 

EC - SEC 1 

IDEA - "On the Design and Security of Block Ciphers" book by X. Lai 
MD2 - RFC 1319 

MD4 - RFC 6150 

MD5 - RFC 1321 

MDC2 - ISO/IEC 10118-2 

RC2 - RFC 2268 

RC4 - RFC 4345 

RC5 - http://people.csail.mit.edu/rivest/Rivest-rc5rev.pdf 
RIPEMD - ISO/IEC 10118-3 


如 何 获取 ERN 许可 , 可 看 这 篇 文章 : How to legally submit an app to Apple’s App Store when 
it uses encryption (or how to obtain an ERN). 


应 用 打包 


A AF Windows 下 路 径 名 过 长 的 问题 IssuUes > Wea} require 加 速 以 及 简单 隐匿 你 的 源 代 
码 ， 你 可 以 通过 极 小 的 源 代码 改动 将 你 的 应 用 打包 成 asar。 


生成 asar 包 


asar 是 一 种 将 多 个 文件 合并 成 一 个 文件 的 类 tar 风格 的 归档 格式 。Electron 可 以 无 需 解 压 ， 
即 从 其 中 读 取 任意 文件 内 容 。 


参照 如 下 步骤 将 你 的 应 用 打包 成 asar 


1. 安装 asar 


$ npm install -g asar 


2. 用 asar pack 打包 


$ asar pack your-app app.asar 


使 用 asar 包 


在 Electron 中 有 两 类 APIs : Node.js 提供 的 Node API 和 Chromium 提供 的 Web API ° 这 两 
种 API 都 支持 从 asar 包 中 读 取 文件 。 


Node API 


由 于 Electron 中 打 了 特别 补丁 ，Node API 中 如 fs.readFile 或 者 require 之 类 的 方法 可 
以 将 asar 视 之 为 虚拟 文件 夹 ， 读 取 asar 里 面 的 文件 就 和 从 真实 的 文件 系统 中 读 取 一 样 。 


例如 ， 假 设 我 们 在 /path/to 文件 夹 下 有 个 example.asar & : 


$ asar list /path/to/example.asar 
/app.js 

/file.txt 

/dir/module.js 

/static/index. html 
/static/main.css 
/static/jquery.min.js 


从 asar 包 读 取 一 个 文件 : 


const fs = require('fs'); 
fs.readFileSync('/path/to/example.asar/file.txt'); 


列 出 asar 包 中 根 目录 下 的 所 有 文件 : 


const fs = require('fs'); 
fs.readdirSync('/path/to/example.asar'); 


使 用 asar 包 中 的 一 个 模块 : 


require('/path/to/example.asar/dir/module.js'); 


你 也 可 以 使 用 BrowserWindow 来 显示 一 个 asar 包 里 的 web 页 面 : 


const BrowserWindow = require('electron').BrowserWindow; 
var win = new BrowserWindow({width: 800, height: 600}); 
win. loadURL('file:///path/to/example.asar/static/index.html'); 


Web API 


在 Web 页面 里 ， 用 file: 协议 可 以 获取 asar 包 中 文件 。 和 Node API 一 样 ， 视 asar & 
如 虚拟 文件 夹 。 


例如 ， 用 g.get 获取 文件 : 


SG 的 了 让 二 

var $ = require('./jquery.min.js'); 

$.get('file:///path/to/example.asar/file.txt', function(data) { 
console.log(data); 


了 


</script> 


1B EAB ESL EL asar 包 


有 些 场景 ， 如 : 核查 asar 包 的 校 验 和 ， 我 们 需要 像 读 取 “ 文 件 "那样 读 取 asar 包 的 内 容 (而 
不 是 当成 虚拟 文件 夹 )。 你 可 以 使 用 内 置 的 original-fs (提供 和 fs 一 样 的 API) 模块 来 


读 取 asar LAB KIS o 


var originalFs = require('original-fs'); 
originalFs.readFileSync('/path/to/example.asar'); 


Node API 缺陷 


尽管 我 们 已 经 尽 了 最 大 努力 使 得 asar BE Node API FHRART HORT ESHA R 
结构 ， 但 仍 有 一 些 底层 Node API 我 们 无 法 保证 其 正常 工作 。 


asar 包 是 只 读 的 


asar 包 中 的 内 容 不 可 和 更改， 所 以 Node APIs 里 那些 可 以 用 来 修改 文件 的 方法 在 对 待 asar 
包 时 都 无 法 正常 工作 。 


Working Directory 在 asar 包 中 无 效 


尽管 asar 包 是 虚拟 文件 夹 ， 但 其 实 并 没有 昌 实 的 目录 架构 对 应 在 文件 系统 里 ， 所 以 你 不 可 
能 将 working Directory 设置 成 asar 包 里 的 一 个 文件 夹 。 将 asar 中 的 文件 夹 以 cwd 形式 
作为 参数 传 入 一 些 API 中 也 会 报错 。 


API 中 的 额外 “ 开 箱 ” 


大 部 分 fs API 可 以 无 需 解压 即 从 asar 包 中 读 取 文件 或 者 文件 的 信息 ， 但 是 在 处 理 一 些 依 
赖 丨 实 文件 路 径 的 底层 系统 方法 时 ，Electron 会 将 所 需 文件 解压 到 临时 目录 下 ， 然 后 将 临时 
目录 下 的 监 实 文件 路 径 传 给 底层 系统 方法 使 其 正 常 工作 。 对 于 这 类 API， 耗 费 会 略 多 一 些 。 


以 下 是 一 些 需要 额外 解压 的 API : 


@ child_process.execFile 

© child_process.execFileSync 
e fs.open 

e fs.openSync 


e process.dlopen - require native 模 块 时 用 到 


fs.stat 获取 的 stat 信息 不 可 靠 


对 asar 包 中 的 文件 取 fs,stat ， 返 回 的 stats 对 象 不 是 精确 值 ， 因 为 这 些 文件 不 是 丨 实 
存在 于 文件 系 统 里 。 所 以 除了 文件 大 小 和 文件 类 型 以 外 ， 你 不 应 该 依赖 stats 对 象 的 值 。 


执行 asar 包 中 的 程序 


Node 中 有 一 些 可 以 执行 程序 的 APl， 如 child process.exec ， child process.spawn 和 
child_process.execFile 等 2 但 只 有 execFile 可 以 执行 asar 包 中 的 程序 9 


因为 exec 和 spawn 允许 command 替代 file 作为 输入 ， 而 command 是 需要 在 shell 下 
执行 的 ， 目 前 没有 可 靠 的 方法 来 判断 command 中 是 否 在 操作 一 个 asar 包 中 的 文件 ， 而 且 
即便 可 以 判断 ， 我 们 依旧 无 法 保证 可 以 在 无 任何 副作用 的 情况 下 替换 command 中 的 文件 路 


y} 
径 。 


打包 时 排除 文件 


如 上 所 述 ， 一 些 Node API 会 在 调用 时 将 文件 解压 到 文件 系统 中 ， 除 了 效率 问题 外 ， 也 有 可 能 
引起 杀毒 软件 的 注意 | 


为 解决 这 个 问题 ， 你 可 以 在 生成 asar 包 时 使 用 --unpack 选项 来 排除 一 些 文件 ， 使 其 不 打 
包 到 asar 包 中 ， 下 面 是 如 何 排除 一 些 用 作 共 享用 途 的 native 模块 的 方法 : 


$ asar pack app app.asar --unpack *.node 


经 过 上 述 命令 后 ， 除 了 生成 的 app.asar 包 以 外 ， 还 有 一 个 包含 了 排除 文件 的 
app.asar.unpacked 文件 夹 ， 你 需要 将 这 个 文件 夹 一 起 拷贝 ， 提供 给 用 户 。 


使 用 原生 模块 


Electron 同样 也 支持 原生 模块 ， 但 由 于 和 官方 的 Node 相 比 使 用 了 不 同 的 V8 引擎 ， 如 果 你 想 
编译 原生 模块 ， 则 需要 手动 设置 Electron 的 headers 的 位 置 。 


原生 Node 模 块 的 兼容 性 


当 Node 开始 换 新 的 V8 引擎 版 本 时 ， 原 生 模 块 可 能 “ 坏 " 掉 。 为 确保 一 切 工作 正常 ， 你 需要 检查 
你 想 要 使 用 的 原生 模块 是 否 被 Electron 内 置 的 Node 支持 。 你 可 以 在 这 里 查看 Electron 内 置 
的 Node 版 本 ， 或 者 使 用 process.version (参考 : 快速 入 门 ) 查 看 。 


考虑 到 NAN 可 以 使 你 的 开发 更 容易 对 多 版 本 Node 的 支持 ， 建 议 使 用 它 来 开发 你 自己 的 模 
块 。 你 也 可 以 使 用 NAN 来 移植 日 的 模块 到 新 的 Nod e 版 本 ， 以 使 它们 可 以 在 新 的 Electron 下 
良好 工作 。 


如 何 安 装 原 生 模 块 


如 下 三 种 方法 教 你 安装 原生 模块 : 


最 简单 方式 
最 简单 的 方式 就 是 通过 electron-rebuild 包 重 新 编译 原生 模块 ， 它 帮 你 自动 完成 了 下 载 
headers、 编 译 原 生 模 块 等 步骤 : 


npm install --save-dev electron-rebuild 


LOR "nom install" 时 ， 也 运行 这 条 命令 
Cree: Pane aie ne rebuild 


在 windows 下 如 果 上 述 命令 遇 到 了 问题 : i 4S: 
. \node_| nodules @ 站 pe cid 


通过 npm 安装 


你 当然 也 可 以 通过 npm 安装 原生 模块 。 大 部 分 步骤 和 安装 普通 模块 时 一 样 ， 除 了 以 下 一 些 系 
统 环境 变量 你 需要 自己 操作 : 


export npm_config_disturl=https://atom.io/download/atom- shell 
export npm_config_target=0.33.14 

export npm_config_arch=x64 

export npm_config_runtime=electron 

HOME=~/.electron-gyp npm install module-name 


通过 node-gyp 安装 
你 需要 告诉 node-gyp 去 哪 下 载 Electron 的 headers， 以 及 下 载 什 么 版 本 : 


$ cd /path-to-module/ 
$ HOME=~/.electron-gyp node-gyp rebuild --target=0.29.1 --arch=x64 --dist-url=https://ato 
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HOME=~/.electron-gyp 设置 去 哪 找 开发 时 的 headers ° 
--target=0.29.1 设置 了 Electron 的 版 本 
--dist-url=... 设置 了 Electron 的 headers 的 下 载 地 址 


--arch=x64 设置 了 该 模块 为 适 配 64 位 操作 系统 而 编译 


主 进 程 调试 


浏览 


器 窗口 的 开发 工具 仅 能 调试 泻 染 器 的 进程 脚本 《比如 web 页面) 。 为 了 提供 一 个 可 以 调 
试 主 进程 的 方法 ，Electron 提供 了 --debug 和 --debug-brk 开关 。 


使 用 如 下 的 命令 行 开 关 来 调试 Electron 的 主 进程 


- -debug=[port] 


当 这 个 开关 用 于 Electron 时 ， 它 将 会 监听 V8 引擎 中 有 关 port 的 调试 器 协议 信息 。 默认 的 
port 是 5858 ° 


--debug-brk=[port ] 


就 像 --debug 一 样 ， 但 是 会 在 第 一 行 暂停 脚本 运行 。 


使 用 node-inspector 来 调试 


备注 : Electron 目前 对 node-inspector 支持 的 不 是 特别 好 ， 如 果 你 通过 node-inspector 的 
console 来 检查 process 对 象 ， 主 进程 就 会 崩溃 。 


1. 确认 你 已 经 安装 了 node-gyp 所 需 工具 
2. 安装 node-inspector 


$ npm install node-inspector 


3. 安装 node-pre-gyp 的 一 个 修订 版 


$ npm install gitt+https://git@github.com/enlight/node-pre-gyp.git#detect-electro 
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4. A Electron 重新 编译 node-inspector vs 模块 (将 target 
参数 修改 为 你 的 Electron 的 版 本 号 ) 


$ node_modules/.bin/node-pre-gyp --target=0.36.2 --runtime=electron --fallback-to-build - 
$ node_modules/.bin/node-pre-gyp --target=0.36.2 --runtime=electron --fallback-to-build - 


1 = >] 








[How to install native modules][how-to-install-native-modules]. 


5. 打开 Electron 的 调试 模式 
你 也 可 以 用 调试 参数 来 运行 Electron 

$ electron --debug=5858 your/app 
或 者 ， 在 第 一 行 暂停 你 的 脚本 : 


$ electron --debug-brk=5858 your/app 


6. 使 用 Electron 开启 node-inspector 服务 


$ ELECTRON_RUN_AS_NODE=true path/to/electron.exe node modules/node-inspector/bin/inspecto 
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7. 加 载 调试 器 界面 


在 Chrome 中 打开 http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=5858 


使 用 Selenium 和 WebDriver 


引 自 ChromeDriver - WebDriver for Chrome: 


WebDriver 是 一 款 开 源 的 支持 多 浏览 器 的 自动 化 测试 工具 。 它 提供 了 操作 网 页 、 用 户 输 
A ` JavaScript 执行 等 能 力 。ChromeDriver 是 一 个 实现 了 WebDriver 与 Chromium 联 
接 协议 的 独立 服务 。 它 也 是 由 开发 了 Chromium 和 WebDriver 的 团队 开发 的 。 


为 了 能 够 使 chromedriver 和 Electron 一 起 正常 工作 ， 我 们 需要 告诉 它 Electron 在 哪 ， 并 且 
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让 它 相 信 Electron 就 是 Chrome 浏览 器 。 


通过 WebDriverJs 配置 

WebDriverJs 是 一 个 可 以 配合 WebDriver 做 测试 的 node 模块 ， 我 们 会 用 它 来 做 个 演示 。 
1. 启动 ChromeDriver 

首先 ， 你 要 下 载 chromedriver ， 然 后 运行 以 下 命令 : 


$ ./chromedriver 
Starting ChromeDriver (v2.10.291558) on port 9515 
Only local connections are allowed. 


记 住 9515 这 个 端口 号 ， 我 们 后 面 会 用 到 
2. 安装 WebDriverJS 


$ npm install selenium-webdriver 


3. 联接 到 ChromeDriver 


在 Electron 下 使 用 selenium-webdriver 和 其 平时 的 用 法 并 没有 大 的 差异 ， 只 是 你 需要 手动 设 
置 连接 ChromeDriver， 以 及 Electron 的 路 径 : 


const webdriver = require('selenium-webdriver'); 


var driver = new webdriver.Builder() 
// "9515" 是 ChromeDriver 使 用 的 端口 
‘UsingServer('http://localhost:9515') 
.withCapabilities({ 
chromeOptions: { 
// 这 里 设置 Electron 的 路 径 
binary: '/Path-to-Your-App.app/Contents/MacOS/Atom', 
} 
}) 


.forBrowser('electron') 
.build(); 


driver.get('http://www.google.com'); 

driver.findElement (webdriver.By.name('q')).sendKeys('webdriver'); 
driver.findElement (webdriver.By.name('btnG')).click(); 
driver.wait(function() { 


return driver.getTitle().then(function(title) { 
return title === 'webdriver - Google Search'; 


3); 
}, 1000); 


driver.quit(); 


通过 WebdriverlO 配置 


WebdriverlO 也 是 一 个 配合 WebDriver 用 来 测试 的 node 模块 


1. 启动 ChromeDriver 
首先 ， 下 载 chromedriver ， 然 后 运行 以 下 命令 : 


$ chromedriver --url-base=wd/hub --port=9515 
Starting ChromeDriver (v2.10.291558) on port 9515 
Only local connections are allowed. 


记 住 9515 端口 ， 后 面 会 用 到 
2. 安装 WebdriverlO 


$ npm install webdriverio 


3. 连接 到 ChromeDriver 


const webdriverio = require('webdriverio'); 
var options = { 
host: "localhost", // 使 用 Localhost 作 为 ChromeDriver 服 务 器 
port: 9515, // "9515" 是 ChromeDriver 使 用 的 端口 
desiredCapabilities: { 
browserName: 'chrome', 
chromeOptions: { 
binary: '/Path-to-Your-App/electron', // Electron 的 路 径 
args: [/* cli arguments */] // 可 选 参数 ， 类 似 : 'app=' + /path/to/your/ar 


}; 
var client = webdriverio.remote(options); 


client 
.init() 
.url('http://google.com' ) 
.setValue('#q', 'webdriverio') 
.click('#btnG') 
.getTitle().then(function(title) { 

console *dog( Title was; i + title); 

}) 


.end(); 
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工作 流程 


无 需 重新 编译 Electron， 只 要 把 app 的 源码 放 到 Electron 的 资源 目录 里 就 可 直接 开始 测试 
了 。 


当然 ， 你 也 可 以 在 运行 Electron 时 传 入 参数 指定 你 app 的 所 在 文件 夹 。 这 步 可 以 免 去 你 找 贝 
一 粘贴 你 的 app 到 Electron 的 资源 目录 。 


DevTools 扩 展 


为 了 使 调试 更 容易 ，Electron 原生 支持 Chrome DevTools Extension 。 


对 于 大 多 数 DevTools 的 扩展 ， 你 可 以 直接 下 载 源码 ， 然 后 通过 
BrowserWindow.addDevToolsExtension API 加 载 它们 。Electron 会 记 住 已 经 加 载 了 哪些 扩展 ， 
所 以 你 不 需要 每 次 创建 一 个 新 window 时 都 调用 Browserwindow.addDevToolsExtension API ° 


注 : React DevTools 目 前 不 能 直接 工作 ， 详 情 留 意 
https://github.com/electron/electron/issues/915 


例如 ， 要 用 React DevTools Extension， 你 得 先 下 载 他 的 源码 : 


$ cd /some-directory 
$ git clone --recursive https://github.com/facebook/react-devtools.git 


参考 react-devtools/shells/chrome/Readme.md 来 编译 这 个 扩展 源码 


然后 你 就 可 以 在 任意 页 面 的 DevTools 里 加 载 React DevTools 了 ， 通 过 控制 台 输 入 如 下 命令 
加 载 扩 展 : 


const BrowserWindow = require('electron').remote.BrowserWindow; 
BrowserWindow. addDevToolsExtension( '/some-directory/react-devtools/shells/chrome'); 


Zp RI JR > TAA Browserwindow.removeDevToolsExtension API (扩展 名 作为 参数 传 入 )， 
该 扩展 在 下 次 打开 DevTools 时 就 不 会 加 载 了 : 


BrowserWindow. removeDevToolsExtension( 'React Developer Tools'); 


DevTools 扩展 的 格式 


理论 上 ，Electron 可 以 加 载 所 有 为 chrome 浏览 器 编写 的 DevTools 扩展 ， 但 它们 必须 存放 在 
LIFRE o IMEA crx 形式 发 布 的 扩展 是 不 能 被 加 载 的 ， 除 非 你 把 它们 解压 到 一 个 文件 夹 
里 。 


后 台 运 行 (background pages) 


Electron 目前 并 不 支持 chrome 扩展 里 的 后 台 运 行 (background pages) 功 能 ， 所 以 那些 依赖 此 
特性 的 DevTools 扩展 在 Electron 里 可 能 无 法 正常 工作 。 


chrome.* APIs 


A Œ chrome 扩展 使 用 了 chrome.* APIs > m 13k 44° KR Electron 中 需要 额外 实现 一 些 代 
码 才 能 使 用 ， 所 以 并 不 是 所 有 的 这 类 扩展 都 已 经 在 Electron 中 实现 完毕 了 。 
考虑 到 并 非 所 有 的 chrome.* APIS 都 实现 完毕 ， 如 果 DevTools 正在 使 用 除了 
chrome.devtools.* 之 外 的 其 它 APls， 这 个 扩展 很 可 能 无 法 正常 工作 。 你 可 以 通过 报告 这 个 
扩展 的 异常 信息 ， 这 样 做 方便 我 们 对 该 扩展 的 支持 。 


使 用 Pepper Flash 插件 


Electron 现在 支持 Pepper Flash 插件 。 要 在 Electron 里 面 使 用 Pepper Flash 插件 ， 你 需要 
手动 设置 Pepper Flash 的 路 径 和 在 你 的 应 用 里 启用 Pepper Flash 。 


保留 一 份 Flash 插件 的 副本 


在 OSX 和 Linux 上 ， 你 可 以 在 Chrome 浏览 器 的 chrome://plugins 页 面 上 找到 Pepper 
Flash 的 插件 信息 。 插 件 的 路 径 和 版 本 会 对 Election 对 其 的 支持 有 帮助 。 你 也 可 以 把 插件 复 
制 到 另 一 个 路 径 以 保留 一 份 副本 。 


添加 插件 在 Electron 里 的 开关 


你 可 以 直接 在 命令 行 中 用 --ppapi-flash-path 和 ppapi-flash-version 或 者 在 app 的 准备 
事件 前 调用 app.commandLine.appendSwitch 这 个 method。 同 时 ， 添 加 browser-window 的 插 
件 开 关 。 例如 : 


// Specify flash path. 设置 flash 路 径 

// On Windows, it might be /path/to/pepflashplayer .dl11 

// On OS X, /path/to/PepperFlashPlayer.plugin 

// On Linux, /path/to/libpepflashplayer.so 
app.commandLine.appendSwitch('ppapi-flash-path', '/path/to/libpepflashplayer.so'); 


// Specify flash version, for example, v17.0.0.169 设置 版 本 号 
app.commandLine.appendSwitch( 'ppapi-flash-version', '17.0.0.169'); 


app.on('ready', function() { 
mainWindow = new BrowserWindow( { 
"width 800, 
"height': 600, 
"web-preferences': { 
"plugins': true 
} 
}); 
mainWindow.loadURL('file://' + _ dirname + '/index.html'); 
// Something else 


}); 


使 用 <webview> 标签 启用 插件 


在 <webview> 标签 里 添加 plugins 属性 


<webview src="http://www.adobe.com/software/flash/about/" plugins></webview> 


使 用 Widevine CDM 插件 


在 Electron ， 你 可 以 使 用 Widevine CDM 插件 装载 Chrome 浏览 器 . 


获取 插件 


Electron 没有 为 Widevine CDM 插件 配制 许可 reasons, 为 了 获得 它 ， 首 先 需要 安装 官方 的 
chrome 浏览 器 ， 这 匹配 了 体系 架构 和 Electron 构建 使 用 的 chrome 版 本 . 


注意 : Chrome 浏览 器 的 主要 版 本 必须 和 Electron 使 用 的 版 本 一 样 ， 否 则 插件 不 会 有 效 ， 虽 然 


navigator.plugins 会 显示 你 已 经 安装 了 它 


Windows & OS X 


在 Chrome ï] 览 器 中 打开 chrome://components/ ? 找到 widevineCdm 并 且 确 定 它 更 新 到 最 
新 版 本 ， 然 后 你 可 以 从 
APP_DATA/Google/Chrome/WidevineCDM/VERSION/_platform_specific/PLATFORM_ARCH/ 路 径 找到 所 


有 的 插件 二 进 制 文件 . 


APP_DATA 是 系统 存放 数据 的 地 方 ， 在 Windows 上 它 是 wLOCALAPPDATA% ,在 OSX 上 它 是 
~/Library/Application Support . VERSION 是 Widevine CDM 插件 的 版 本 字符 串 , 类 似 


1.4.8.866 . PLATFORM 是 mac 或 win. ARCH Æ x86 或 x64. 

在 Windows， 必 要 的 二 进 制 文件 是 widevinecdm.dll and widevinecdmadapter.dll ,在 OSX 
> 它们 是 libwidevinecdm.dylib 和 widevinecdmadapter.plugin . 你 可 以 将 它们 复制 到 任何 你 
喜欢 的 地 方 ， 但 是 它们 必须 要 放 在 一 

Linux 


在 Linux > Chrome 浏览 器 将 插件 的 二 进 制 文件 装载 在 一 起 ,你 可 以 在 /opt/google/chrome 
下 找到 ,文件 名 是 libwidevinecdm.so 和 libwidevinecdmadapter.so . 


使 用 插件 


在 获得 了 插件 文件 后 ， 你 可 以 使 用 - -widevine-cdm-path 命令 行 开 关 来 将 
widevinecdmadapter 的 路 径 传 递 给 Electron , 插件 版 本 使 用 --widevine-cdm-version 开关 . 


注意 : 虽然 只 有 widevinecdmadapter 的 二 进 制 文件 传递 给 了 Electron，widevinecdm 二 进 制 文 


必须 在 app 模块 的 ready 事件 触发 之 前 使 用 命令 行 开 关 ， 并 且 page 使 用 的 插件 必须 激活 . 


示例 代码 : 


// You have to pass the filename of ‘widevinecdmadapter here, it is 

// * ~widevinecdmadapter.plugin’ on OS X, 

// * ~libwidevinecdmadapter.so~ on Linux, 

// * ~widevinecdmadapter.dll° on Windows. 

app.commandLine.appendSwitch( 'widevine-cdm-path', '/path/to/widevinecdmadapter.plugin'); 
// The version of plugin can be got from ‘chrome://plugins page in Chrome. 
app.commandLine.appendSwitch( 'widevine-cdm-version', '1.4.8.866'); 


var mainWindow = null; 
app.on('ready', function() { 
mainWindow = new BrowserWindow( { 
webPreferences: { 
// The ‘plugins have to be enabled. 
plugins: true 


验证 插件 


为 了 验证 插件 是 否 工作 ， 你 可 以 使 用 下 面 的 方法 : 


e 打开 开发 者 工具 查看 是 否 navigator .plugins 包含 了 Widevine CDM 插件 . 
e 打开 https://shaka-player-demo.appspot.com/ 加 载 一 个 使 用 widevine 的 manifest. 
e 打开 http://www.dash-player.com/demo/drm-test-area/, 检查 是 否 界 面 输出 

bitdash uses Widevine in your browser ,然后 播放 video. 


教程 


简介 


Electron 可 以 让 你 使 用 纯 JavaScript 调用 丰富 的 原生 APIS 来 创造 桌面 应 用 。 你 可 以 把 它 看 作 
是 专注 于 桌面 应 用 而 不 是 web 服务 器 的 ，io.js 的 一 个 变 体 。 


这 不 意味 着 Electron 是 绑 定 了 GUI 库 的 JavaScript ° 7% > Electron 使 用 web 页 面 作为 它 的 
GUI， 所 以 你 能 把 它 看 作成 一 个 被 JavaScript 控制 的 ， 精 简 版 的 Chromium 浏览 器 。 


进程 


在 Electron 里 ， 运 行 package.json 里 main 脚本 的 进程 被 称 为 主 进程 。 在 主 进程 运行 的 脚 
本 可 以 以 创建 web 页 面 的 形式 展示 GUI。 


宣 染 进程 


由 于 Electron 使 用 Chromium 来 展示 页 面 ， 所 以 Chromium 的 多 进程 结构 也 被 充分 利用 。 
A Electron 的 页 面 都 在 运行 着 自己 的 进程 ， 这 样 的 进程 我 们 称 之 为 泻 染 进程 。 


在 一 般 浏 览 器 中 ， 网 页 通常 会 在 沙 盒 环 境 下 运行 ， 并 且 不 允许 访问 原生 资源 。 然 而 ，Electron 
用 户 拥有 在 网 页 En io.js 的 APIs 的 能 力 ， 可 以 与 底层 操作 系统 直接 交互 。 


进程 与 泻 染 进程 的 区 别 


主 进程 使 用 BrowserWindow 实例 创建 网 页 。 每 个 BrowserWindow 实例 都 在 自己 的 泻 染 进程 
运行 着 一 个 网 页 。 当 一 个 BrowserWindow 实例 被 销毁 后 ， 相 应 的 泻 染 进程 也 会 被 终止 。 


is 


主 进程 管理 所 有 页 面 和 与 之 对 应 的 泻 当 进程。 每 个 泻 染 进程 都 是 相互 独立 的 ， 并 且 只 关心 他 
们 自己 的 网 页 。 
由 于 在 网 页 里 管理 原生 GUI 资源 是 非常 危险 而 且 容 易 造 成 资源 泄露 ， 所 以 在 网 页 面 调用 GUI 


eae ie pleas o 如果 你 想 在 网 页 里 使 用 GUI 操作 ， 其 对 应 的 泻 染 进程 必须 与 主 
进程 进行 通讯 ， 请 求 主 进程 进行 相关 的 GUI 操作 。 


在 Electron， 我 们 提供 用 于 在 主 进程 与 演 染 进程 之 间 通 讯 的 ipc 模块 。 并 且 也 有 一 个 远程 进程 
调用 风格 的 通讯 模块 remote 。 


打造 你 第 一 个 Electron 应 用 


大 体 上 ， 一 个 Electron 应 用 的 目录 结构 如 下 : 


your -app/ 
| 一 package.json 
| main.js 


L— index.html 


package.json 的 格式 和 Node 的 完全 一 致 ， 并 且 那 个 被 main 字段 声明 的 脚本 文件 是 你 的 应 
用 的 启动 脚本 ， 它 运行 在 主 进程 上 。 你 应 用 里 的 package.json 看 起 来 应 该 像 : 


{ 
"name" : "your-app", 
WweRSTON! = “Ona .014, 
"main" Madness 
} 


注意 : 如 果 main 字段 没有 在 package.json 声明 ，Electron 会 优先 加 载 index.js ° 


main.js 应 该 用 于 创建 窗口 和 处 理 系统 时 间 ， 一 个 典型 的 例子 如 下 : 


var app = require('app'); // 控制 应 用 生命 周期 的 模块 。 
var BrowserWindow = require('browser-window'); // 创建 原生 浏览 





窗口 的 模块 


// 保持 一 个 对 于 window 对 象 的 全 局 引用 ， 不 然 ， 当 JavaScript 被 GC， 
// window 会 被 自动 地 关闭 
var mainWindow = null; 


// 当 所 有 窗口 被 关闭 了 ， 退 出 
app.on( 'window- a11- closed', function() { 
Uf Hs 0 上 ， 通 常用 户 在 明确 地 按 下 Cmd + Q 之 前 
// 应 用 会 保持 活动 状态 
if (process.platform != 'darwin') { 
app.quit(); 





} 
}); 
// š Electron 完成 了 初始 化 并 且 准 备 创建 浏览 
// 这 个 方法 就 被 调用 
app.on( ready function() { 
// 创建 浏览 器 窗口 。 
mainWindow = new BrowserWindow({width: 800, height: 600}); 





窗口 的 时 候 









// 加 载 应 用 的 index.html 
mainWindow.loadURL('file://' + _ dirname + '/index.html'); 


// 打开 开发 工具 
mainWindow.openDevTools(); 


// % window 被 关闭 ， 这 个 事件 会 被 发 出 
mainWindow.on('closed', mes em ) { 
// 取消 引用 window 对 E 如 果 你 的 应 用 支持 多 多 窗口 的 话 ， 





// 通常 会 把 多 个 window 对 象 存 放 在 一 个 数 乡 
// BIRTA ` 
mainWindow = null; 

}); 


3); 


最 后 ， 你 想 展 示 的 index.html 
<!DOCTYPE html> 
ml> 


itle>Hello World!</title> 





<hi>Hello Gordels wia 


We are using io. ee <s t>document.write(process.version)</script> 
and Electron <scrip NE write(process.versions[ ' electron’ oR Slips 
</body> 
</html> 


运行 你 的 应 用 


一 旦 你 创建 了 最 初 的 main.js °’ index.html 和 package.json 这 几 个 文件 ， 你 可 能 会 想 尝 
试 在 本 地 运行 并 测试 ， 看 看 是 不 是 和 期 望 的 那样 正常 运行 


electron-prebuild 


如 果 你 已 经 用 npm 全 局 安装 了 electron-prebuilt ， 你 只 需要 按照 如 下 方式 直接 运行 你 的 应 
用 : 


electron . 


如 果 你 是 局 部 安装 ， 那 运行 


./node_modules/.bin/electron . 


手工 下 载 Electron 二 进 制 文件 


如 果 你 手工 下 载 了 Electron 的 二 进 制 文件 ， 你 也 可 以 直接 使 用 其 中 的 二 进 制 文 件 直接 运行 你 
的 应 用 。 
Windows 


$ .\electron\electron.exe your-app\ 


Linux 


$ ./electron/electron your -app/ 


OS X 


$ ./Electron.app/Contents/MacOS/Electron your -app/ 


Electron.app £m Electron 发 布 包 ， 你 可 以 在 这 里 下 载 到 。 


以 发 行 版 本 运行 


在 你 完成 了 你 的 应 用 后 
运行 应 用 。 


你 可 以 按照 应 用 部 署 指 导 发 布 一 个 版 本 ， 并 且 以 已 经 打包 好 的 形式 


i 六 
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呆 面 环境 集成 
不 同 的 操作 系统 在 各 自 的 桌面 应 用 上 提供 了 不 同 的 特性 。 例 如 ， 在 windows 上 应 用 曾经 打开 
的 文件 会 出 现在 任务 栏 的 跳 转 列表 ， 在 Mac 上 ， 应 用 可 以 把 自 定义 菜单 放 在 鱼 眼 菜单 上 。 


本 章 将 会 说 明 怎 样 使 用 Electron APIs 把 你 的 应 用 和 桌面 环境 集成 到 一 块 。 


最 近 文 档 (Windows & OS X) 


Windows 和 OS X 提供 获取 最 近 文 档 列 表 的 便捷 方式 ， 那 就 是 打开 跳 转 列 表 或 者 鱼 眼 菜单 。 


Recent 

E] Cats.bt 

|_| Letter.bt 

|_| GroceryList.txt 
|_| Docl.tet 


“| Notepad 
@& Unpin this program from taskbar 


Close window 





跳 转 列表 : 
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BIRR 


AB tmp 

@ raven 

@ atom 

@ chromium-source-tarball 


E app.md - /Users/zcbenz/codes/raven - Atom 


Options > 
Show All Windows 

Hide 

Quit 





为 了 增加 一 个 文件 到 最 近 文件 列表 ， 你 可 以 使 用 API: 


var app = require('app'); 
app.addRecentDocument('/Users/USERNAME/Desktop/work.type'); 


或 者 你 也 可 以 使 用 API 来 清空 最 近 文件 列表 。 


app.clearRecentDocuments(); 


Windows % 3% 
为 了 这 个 特性 在 Windows 上 表现 正常 ， 你 的 应 用 需要 被 注册 成 为 一 种 文件 类 型 的 句柄 ， 否 


则 ， 在 你 注册 之 前 ， 文 件 不 会 出 现在 跳 转 列表 。 你 可 以 在 里 找到 任 
何 关 于 注册 事宜 的 说 明 。 


OSX 需 注 意 


当 一 个 文件 被 最 近 文 件 列表 请 求 时 ， app 模块 里 的 open-file 事件 将 会 被 发 出 。 
自 定义 的 鱼 眼 菜单 (OS X) 
OSX 可 以 让 开发 者 定制 自己 的 菜单 ， 通 常会 包含 一 些 常 用 特性 的 快捷 方式 。 


菜单 中 的 终端 


V $ raven — Atom Helper — 86x26 
E raven 一 bash — 86x26 


New Window 

New Window with Settings 
New Command... 

New Remote Connection... 


Options 


Show All Windows 
Hide 
Quit 














a 和 — = 


使 用 app.dock.setMenu API 来 设置 你 的 菜单 ， 这 仅 在 OS X 上 可 行 : 
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var app = require('app'); 
var Menu = require('menu'); 
var dockMenu = Menu.buildFromTemplate([ 
{ label: 'New Window', click: function() { console.log('New Window'); } }, 
{ label: 'New Window with Settings', submenu: [ 
{ label: 'Basic' }, 
{ label: 'Pro'} 
]}, 
{ label: 'New Command...'} 
l); 


app.dock.setMenu(dockMenu) ; 


Fil P 4£ $ (Windows) 


在 Windows， 你 可 以 特别 定义 跳 转 列表 的 Tasks 目录 的 行为 ， 引 用 MSDN 的 文档 : 


Applications define tasks based on both the program's features and the key things a 
user is expected to do with them. Tasks should be context-free, in that the application 


does not need to be running for them to work. They should also be the statistically most 


common actions that a normal user would perform in an application, such as compose 
an email message or open the calendar in a mail program, create a new document in a 
word processor, launch an application in a certain mode, or launch one of its 
subcommands. An application should not clutter the menu with advanced features that 
standard users won't need or one-time actions such as registration. Do not use tasks 
for promotional items such as upgrades or special offers. 


It is strongly recommended that the task list be static. It should remain the same 
regardless of the state or status of the application. While it is possible to vary the list 
dynamically, you should consider that this could confuse the user who does not expect 
that portion of the destination list to change. 


IE 的 任务 
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Frequent 

“@ MSN.com 

© Xbox.com | Home 

区 Microsoft Corporation 
Tasks 

€39 Start InPrivate Browsing 


[* Open new tab 


é Internet Explorer 


@ Unpin this program from taskbar 


Close window 





BS) 不 同 于 OS X 49 BIRR > Windows 上 的 用 户 任 
务 表现 得 更 像 一 个 快捷 方式 ， 比 如 当 用 户 点 击 一 个 任务 ， 一 个 程序 将 会 被 传 入 特定 的 参数 并 


你 可 以 使 用 app.setUserTasks API 来 设置 你 的 应 用 中 的 用 户 任务 : 
var app = require('app'); 
app.setUserTasks([ 
program: process.execPath, 
arguments: '--new-window', 
iconPath: process.execPath, 
iconIndex: 0, 
title: 'New Window', 
description: 'Create a new window' 


} 
l); 
调用 app.setUserTasks 并 传 入 空 数组 就 可 以 清除 你 的 任务 列表 : 


app.setUserTasks([]); 


当 你 的 应 用 关闭 时 ， 用 户 任务 会 仍然 会 出 现 ， 在 你 的 应 用 被 卸载 前 ， 任 务 指 定 的 图 标 和 程序 
的 路 径 必须 是 存在 的 。 
缩 略图 工具 栏 


在 Windows， 你 可 以 在 任务 栏 上 添加 一 个 按钮 来 当 作 应 用 的 缩 略 图 工具 栏 。 它 将 提供 用 户 一 
种 用 户 访问 常用 窗口 的 方式 ， 并 且 不 需要 恢复 或 者 激活 窗口 。 


在 MSDN， 它 被 如 是 说 : 


立 
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This toolbar is simply the familiar standard toolbar common control. It has a maximum 
of seven buttons. Each button's ID, image, tooltip, and state are defined in a structure, 
which is then passed to the taskbar. The application can show, enable, disable, or hide 
buttons from the thumbnail toolbar as required by its current state. 


For example, Windows Media Player might offer standard media transport controls such 
as play, pause, mute, and stop. 


Windows Media Player 的 缩 略图 工具 栏 


[F] Windows Media Player 





| 人 尔 可 以 使 用 
BrowserWindow.setThumbarButtons 来 设置 你 的 应 用 的 缩 略图 工具 栏 。 
var BrowserWindow = require('browser-window' ); 


var path = require('path'); 
var win = new BrowserWindow( { 


width: 800, 
height: 600 
}); 


win.setThumbarButtons([ 


tooltip: "button1", 

icon: path.join(__dirname, ‘buttoni.png'), 

click: function() { console.log("button2 clicked"); } 
}, 
{ 

tooltip: "button2", 

icon: path.join(__dirname, 'button2.png'), 

flags:['enabled', 'dismissonclick'], 

click: function() { console.log("button2 clicked."); } 


} 
l); 


iK 


调用 Browserwindow.setThumbarButtons 并 传 入 空 数组 即 可 清空 缩 略 图 工具 本 


\ 


win.setThumbarButtons([]); 
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Unity launcher 快捷 方式 (Linux) 


在 Unity, 你 可 以 通过 改变 desktop 文件 来 增加 自 定义 运行 器 的 快捷 方式 ， 详 情 看 Adding 


shortcuts to a launcher ° 
Audacious 运行 器 的 快捷 方式 : 


Start 


Pause 


Stop 
Next 


(2) pps coe 
Am 


ChangeWallpaper 
Live Earth Wallpaper 


Wallch 


Unlock From launcher 





Ea 


任务 栏 的 进度 条 (Windows & Unity) 


在 Windows， 进 度 条 可 以 出 现在 一 个 任务 栏 按钮 之 上 。 这 可 以 提供 进度 


用 户 切 换 应 用 窗口 


Unity DE 也 具有 同样 的 特性 ， 在 运行 器 上 显示 进度 条 。 


在 任务 栏 上 的 进度 条 : 


在 Unity 运行 器 上 的 进度 条 





度 信 ， 


Quy 


a 


给 用 户 而 不 需要 





给 一 个 窗口 设置 进度 条 ， 你 可 以 调用 BrowserWindow.setProgressBar API : 


var window = new BrowserWindow({...}); 
window.setProgressBar(0.5); 


在 OS X， 一 个 窗口 可 以 设置 它 展 示 的 文件 ， 文 件 的 图 标 可 以 出 现在 标题 栏 ， 当 用 户 
Command-Click 或 者 Control-Click 标题 栏 ， 文 件 路 径 弹 窗 将 会 出 现 。 


展示 文件 弹 窗 菜单 : 





OW EA TE Users/zcbenz/codes/raven — Atom 
© tutorial 




















© docs 
125 = raven 
126 |) codes 
& zcbenz | TT 
127 a F app.setUserTasks~ with empty array: 
128 sers 


129 =) Macintosh HD 
130 m macbook 

131 Ws 
132 


你 可 以 调用 BrowserWindow.setRepresentedFilename 和 
BrowserWindow.setDocumentEdited APIs : 


var window = new BrowserWindow({...}); 
window.setRepresentedFilename('/etc/passwd'); 
window.setDocumentEdited(true); 


在 线 /离线 事件 探测 


使 用 标准 HTML5 APIs 可 以 实现 在 线 和 离线 事件 的 探测 ， 就 像 以 下 例子 : 
main.js 


var app = require('app'); 
var BrowserWindow = require('browser-window' ); 
var onlineStatuswWindow; 


app.on('ready', function() { 


onlineStatusWindow = new BrowserWindow({ width: ©, height: 0, show: false }); 
onlineStatusWindow. loadURL('file://' + _ dirname + '/online-status.html'); 


3); 


online-status.html 


<!DOCTYPE html> 


<html> 
<body> 
<script> 
var alertOnlineStatus = function() { 
window.alert(navigator.onLine ? 'online' : ‘offline'); 
}; 


window.addEventListener('online', alertOnlineStatus); 
window.addEventListener('offline', alertOnlineStatus); 


alertOnlineStatus(); 
</script> 
</body> 
</html> 


也 会 有 人 想 要 在 主 进程 也 有 回应 这 些 事件 的 实例 。 然 后 主 进程 没有 navigator xt BA wh A Ae 
直接 探测 在 线 还 是 离线 。 使 用 Electron 的 进程 间 通 讯 工 具 ， 事 件 就 可 以 在 主 进程 被 使 ， 就 像 
下 面 的 例子 : 


main.js 


var app = require('app'); 

var ipc = require('ipc'); 

var BrowserWindow = require('browser-window' ); 
var onlineStatusWindow; 


app.on('ready', function() { 
onlineStatusWindow = new BrowserWindow({ width: ©, height: 0, show: false }); 
onlineStatusWindow.loadURL('file://' + _ dirname + '/online-status.html'); 


3); 


ipc.on('online-status-changed', function(event, status) { 
console.log(status); 


}); 


online-status.html 


<!DOCTYPE html> 
<html> 
<body> 
<script> 
var ipc = require('ipc'); 
var updateOnlineStatus = function() { 
ipc.send('online-status-changed', navigator.onLine ? 'online' : 'offline'); 


T 


window.addEventListener('online', updateOnlineStatus) ; 
window.addEventListener('offline', updateOnlineStatus); 


updateOnlineStatus(); 
</script> 
</body> 
</html> 


API 档 


所 有 的 Node.js's built-in modules 在 Electron 中 都 可 用 ， 并 且 所 有 的 node 的 第 三 方 组 件 也 可 以 
放心 使 用 (包括 自身 的 模块 ) 。 


Electron 也 提供 了 一 些 额 外 的 内 置 组 件 来 开发 传统 桌面 应 用 。 一 些 组 件 只 可 以 在 主 进程 中 使 
用 ， 一 些 只 可 以 在 泻 染 进程 中 使 用 ， 但 是 也 有 部 分 可 以 在 这 2 种 进程 中 都 可 使 用 。 


基本 规则 : GUI 模块 或 者 系统 底层 的 模块 只 可 以 在 主 进程 中 使 用 。 要 使 用 这 些 模块 ， 你 应 当 很 
熟悉 主 进 程 Vs 渔 染 进程 脚本 的 概念 


主 进程 脚本 看 起 来 像 个 普通 的 nodejs 脚 本 


const electron = require('electron'); 
const app = electron.app; 
const BrowserWindow = electron.BrowserWindow; 


var window = null; 


app.on('ready', function() { 
window = new BrowserWindow({width: 800, height: 600}); 
window. loadURL('https://github.com'); 


3); 


泻 染 进程 和 传统 的 web 界 面 一 样 ， 除 了 它 具 有 使 用 node 模 块 的 能 力 : 


<!DOCTYPE html> 
<html> 
<body> 
<script> 
const remote = require('electron').remote; 
console.log(remote.app.getVersion()); 
</script> 


</body> 
</html> 
如 果 想 运行 应 用 ， 参 考 Run your app ° 


解构 任务 


如 果 你 使 用 的 是 CoffeeScript 或 Babel， 你 可 以 使 用 destructuring assignment 来 让 使 用 内 置 模 
块 更 简单 : 


const {app, BrowserWindow} = require('electron'); 


然而 如 果 你 使 用 的 是 普通 的 JavaScript， 你 就 需要 等 到 Chrome 支 持 ES6 了 。 


使 用 内 置 模块 时 禁用 昌 样 式 


在 版 本 v0.35.0 之 前 所 有 的 内 置 模块 都 需要 按 造 require( 'module-name') 形 式 来 使 用 > BR 
CAIR Fn RN REZ IEA PAH RHE © 


为 了 完整 的 禁用 昌 样 式 ， 你 可 以 设置 环境 变量 ELECTRON_HIDE_INTERNAL_MODULES : 
process.env.ELECTRON_HIDE_INTERNAL_MODULES = 'true' 
或 者 调用 hideInternalModules API: 


require('electron').hideInternalModules() 


进程 
Electron 中 的 process 对 象 与 upstream node 中 的 有 以 下 的 不 同 点 : 


e process.type String - 进程 类 型 , 可 以 是 browser (i.e. main process) 或 renderer . 
e process.versions['electron'] String - Electron 的 版 本 . 
e process.versions['chrome'] String - Chromium 的 版 本 . 
e process.resourcesPath String - JavaScript 源 代码 路 径 . 
e process.mas Boolean - 在 Mac App Store 创建 ， 它 的 值 为 true ， 在 其 它 的 地 方 值 为 


undefined . 


事件 


= +: loaded' 
在 Electron 已 经 加 载 了 其 内 部 预 置 脚本 和 它 准 备 加 载 主 进程 或 泻 染 进程 的 时 候 触发 . 


当 node 被 完全 关闭 的 时 候 ， 它 可 以 被 预 加 载 脚本 使 用 来 添加 (原文 : removed) 与 node 无 关 的 全 
局 符号 来 回 退 到 全 局 范围 : 


yy Pe sA c 
// pretoaa.js 
var _setImmediate = setImmediate; 

var _clearImmediate = clearImmediate; 


process.once('loaded', function() { 


global.setImmediate = _setImmediate; 
global.clearImmediate = _clearImmediate; 
}); 


属性 
process.noAsar 
设置 它 为 true 可 以 使 asar 文件 在 node 的 内 置 模块 中 实效 . 
方法 
process 对 象 有 如 下 方法 : 


process.hang() 


使 当前 进程 的 主线 成 挂 起 . 


process.setFdLimit(maxDescriptors) OS X Linux 


è maxDescriptors Integer 


设置 文件 描述 符 软 限制 于 maxDescriptors 或 硬 限制 与 os, 无 论 它 是 否 低 于 当前 进程 . 


支持 的 Chrome 命令 行 开关 


页 列 出 了 Chrome 浏 览 器 和 Electron 支 持 的 命令 行 开 关 . 你 也 可 以 在 app 模 块 的 ready 事 件 发 
k Z Fy 4% M app.commandLine.appendSwitch 来 添加 它们 到 你 应 用 的 main 脚 本 里 面 : 


const app = require('electron').app; 
app.commandLine.appendSwitch('remote-debugging-port', '8315'); 
app.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1'); 
app.on('ready', function() { 


3); 


--client-certificate= path 


设置 客户 端的 证 书 文 件 path . 


--ignore-connections-limit= domains 


忽略 用 ， 分 隔 的 domains 列表 的 连接 限制 . 


--disable-http-cache 


禁止 请 求 HTTP 时 使 用 磁盘 缓存 . 


--remote-debugging-port= port 


在 指定 的 端口 通过 HTTP 开启 远程 调试 . 


--jS-flags= flags 


指定 引擎 过 渡 到 JS 引擎 . 


在 启动 Electron 时 ， 如 果 你 想 在 主 进 程 中 激活 flags ， 它 将 被 转换 . 


$ electron --js-flags="--harmony_proxies --harmony_collections" your-app 


--proxy-server= address:port 


使 用 一 个 特定 的 代理 服务 器 ， 它 将 比 系统 设置 的 优先 级 更 高 .这 个 开关 只 有 在 使 用 HTTP 协议 
时 有 效 ， 它 包含 HTTPS 和 WebSocket 请 求 . 值得 注意 的 是 ， 不 是 所 有 的 代理 服务 器 都 支持 
HTTPS 和 WebSocket 请 求 . 


--proxy-bypass-list= hosts 
让 Electron 使 用 (原文 :bypass) 提供 的 以 semi-colon 分 隔 的 hosts 列 表 的 代理 服务 器 .这 个 开关 
只 有 在 使 用 --proxy-server 时 有 效 . 
例如 : 

app.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4: 
Eee __ }§ 


将 会 为 所 有 的 hosts 使 用 代理 服务 器 ， 除 了 本 地 地 址 ( localhost , 127.0.0.1 etc.), 
google.com 子 域 , 以 foo.com 结尾 的 hosts， 和 所 有 类 似 1.2.3.4:5678 的 . 





--proxy-pac-url= url 


在 指定 的 url 上 使 用 PAC 脚本 . 


--NO-proxy-server 


不 使 用 代理 服务 并 且 总 是 使 用 直接 连接 .忽略 所 有 的 合理 代理 标志 . 


--host-rules= rules 


一 个 去 号 分 隔 的 _ rule 列表 来 控制 主机 名 如 何 映射 . 
例如 : 


© MAP * 127.0.0.1 强制 所 有 主机 名 映射 到 127.0.0.1 

e MAP *.google.com proxy 强制 所 有 google.com 子 域 使 用 "proxy". 

e MAP test.com [::1]:77 强制 "test.com" 使 用 IPv6 回环 地 址 . 也 强制 使 用 端口 77. 

e MAP * baz, EXCLUDE www.google.com 重新 全 部 映射 到 "baz", 除了 "www.google.com". 


这 些 映射 适用 于 终端 网 络 请 求 (TCP 连接 和 主机 解析 以 直接 连接 的 方式 , 和 connect 以 代理 
连接 , 还 有 终端 host 使 用 socks 代理 连接 ). 


--host-resolver-rules= rules 


类 似 --host-rules ， 但 是 rules 只 适合 主机 解析 . 


--ignore-certificate-errors 


忽略 与 证 书 相 关 的 错误 . 


--ppapi-flash-path= path 


设置 Pepper Flash 插 件 的 路 径 path . 


--ppapi-flash-version= version 


设置 Pepper Flash 插 件 版 本 号 . 


--log-net-log= path 


使 网 络 日 志 事 件 能 够 被 读 写 到 path. 


--ss|l-version-fallback-min= version 


设置 最 简化 的 SSL/TLS 版 本 号 ("tls1", "tls1.1" or "tls1.2") > TLS 可 接受 回 退 . 


--Cipher-suite-blacklist= cipher_suites 


指定 各 号 分 隔 的 SSL 密码 套件 列表 实效 . 


--disable-renderer-backgrounding 


防止 Chromium 降低 隐藏 的 演 染 进程 优先 级 . 


这 个 标志 对 所 有 演 染 进程 全 局 有 效 ， 如 果 你 只 想 在 一 个 窗口 中 禁止 使 用 ， 你 可 以 采用 hack 方 
法 playing silent audio. 


--enable-logging 


打印 Chromium 信息 输出 到 控制 台 . 


如 果 在 用 户 应 用 加 载 完成 之 前 解析 app.commandLine.appendSwitch ? 这 个 开关 将 实效 ， 但 是 你 
可 以 设置 ELECTRON_ENABLE_LOGGING 环境 变量 来 达到 相同 的 效果 . 


--V= log level 


设置 默认 最 大 活跃 V-logging 标准 ; 默认 为 0. 通 常 V-logging 标准 值 为 肯定 值 . 


这 个 开关 只 有 在 --enable-logging 开局 时 有 效 . 


--vmodule= pattern 
赋予 每 个 模块 最 大 的 V-logging levels 来 覆盖 --v 给 的 值 .E.g. my_module=2,foo*=3 会 改变 
所 有 源 文 件 my_module.* and foo*.* 的 代码 中 的 logging level . 


任何 包含 向 前 的 (forward slash) 或 者 向 后 的 (backward slash) 模 式 将 被 测试 用 于 阻止 整个 路 径 
名 ， 并 且 不 仅 是 E.g 模 块 . */foo/bar/*=2 将 会 改变 所 有 在 foo/bar 下 的 源 文件 代码 中 的 
logging level . 


这 个 开关 只 有 在 --enable-logging 开局 时 有 效 . 


环境 变量 


一 些 Electron 的 行为 受到 环境 变量 的 控制 ， 因 为 他 们 的 初始 化 比 命令 行 和 应 用 代码 更 早 . 
POSIX shells 的 例子 : 


$ export ELECTRON_ENABLE_LOGGING=true 
$ electron 


Windows 控制 台 : 


> Set ELECTRON_ENABLE_LOGGING=true 
> electron 


ELECTRON_RUN_AS_NODE 


类 似 node.js 普 通 进程 启动 方式 . 


ELECTRON_ENABLE_LOGGING 


打印 Chrome 的 内 部 日 志 到 控制 台 . 


ELECTRON_LOG_ASAR_READS 


4 Electron 读 取 ASA 文档 ， 把 read offset 和 文档 路 径 做 日 志 记 录 到 系统 tmpdir .结果 文件 
将 提供 给 ASAR 模块 来 优化 文档 组 织 . 


ELECTRON_ENABLE_ STACK_DUMPING 


当 Electron 崩 演 的 时 候 ， 打 印 堆栈 记录 到 控制 台 . 


a 


如 果 crashReporter 已 经 启动 那么 这 个 环境 变量 实效 . 


ELECTRON DEFAULT ERROR MODE Windows 


当 Electron 崩 江 的 时 候 ， 显 示 wWindows 的 崩溃 对 话 框 . 


如 果 crashReporter 已 经 启动 那么 这 个 环境 变量 实效 . 


ELECTRON NO ATTACH CONSOLE Windows 


不 可 使 用 当前 控制 台 . 
ELECTRON FORCE WINDOW MENU BAR Linux 
不 可 再 Linux 上 使 用 全 局 菜单 栏 . 


ELECTRON_HIDE_INTERNAL_MODULES 


关闭 昌 的 内 置 模块 如 require('ipc') 的 通用 模块 . 


自 定义 的 DOM 元 素 


File 对 象 


为 了 让 用 户 能 够 通过 HTML5 的 file API 直 接 操作 本 地 文件 ，DOM 的 File 接 口 提供 了 对 本 地 文件 
的 抽象 。Electron 在 File 接 口中 增加 了 一 个 path 属 性 ， 它 是 文件 在 系统 中 的 趴 实 路 径 。 


获取 拖 动 到 APP 中 文件 的 卜 实 路 径 的 例子 : 


<div id="holder"> 
Drag your file here 
</div> 


<script> 

var holder = document.getElementById('holder'); 

holder.ondragover = function () { 
return false; 

J; 

holder.ondragleave = holder.ondragend = function () { 
return false; 

J; 

holder.ondrop = function (e) { 
e.preventDefault(); 
var file = e.dataTransfer.files[0]; 
console.log('File you dragged here is', file.path); 
return false; 

}; 


</script> 


<webview> 标签 


使 用 webview 标签 来 把 ‘guest’ 内 容 (例如 web pages ) #& AZ) 1% 49 Electron app 中 . guest 
内 容 包 含 在 webview 容器 中 .一 个 谋 入 你 应 用 的 page 控 制 着 guest 内 容 如 何 布局 摆 放 和 表达 含 
MX. 


与 iframe 不 同 ，webview 和 你 的 应 用 运行 的 是 不 同 的 进程 . 它 不 拥有 泻 汪 进程 的 权限 ， 并 且 
应 用 和 上 殴 入 内 容 之 间 的 交互 全 部 都 是 异步 的 .因为 这 能 保证 应 用 的 安全 性 不 受 具 入 内 容 的 影响 . 


aT 


把 一 个 web page 嵌入 到 你 的 app， 首 先 添加 webview 4%% #1% Happtt ik Apage(R* 
guest content). 在 一 个 最 简单 的 webview 中 ， 它 包含 了 web page 的 文件 路 径 和 一 个 控制 
webview 容器 展示 效果 的 css 样 式 : 


<webview id="foo" src="https://www.github.com/" style="display:inline-block; width:640px; 


了 


ae 


如 果 想 随时 控制 guest 内 容 ， 可 以 添加 JavaScript 脚本 来 监听 webview 事件 使 用 webview 
方法 来 做 出 响应 . 这 里 是 2 个 事件 监听 的 例子 : 一 个 监听 web page 准备 加 载 ， 另 一 个 监听 
web page 停止 加 载 ， 并 且 在 加 载 的 时 候 显示 一 条 "loading..." 信息 : 





<script> 
onload = function() { 
var webview = document.getElementById("foo"); 
var indicator = document.querySelector(".indicator"); 


var loadstart = function() { 


indicator.innerText = "loading..."; 
} 
var loadstop = function() { 
indicator.innerText = ""; 
} 


webview.addEventListener("did-start-loading", loadstart); 
webview.addEventListener("did-stop-loading", loadstop); 


</script> 


webview 标签 有 下 面 一 些 属 性 : 


src 


<webview src="https://www.github.com/"></webview> 


将 一 个 可 用 的 url 做 为 这 个 属性 的 初始 值 添加 到 顶部 导航 . 
如 果 把 当前 页 的 Src 添加 进去 将 加 载 当前 page. 


src 同样 可 以 填 data urls， 例 如 data:text/plain,Hello, world! . 
autosize 


<webview src="https://www.github.com/" autosize="0n" minwidth="576" minheight="432"></web 
可 一 一 一 


如 果 这 个 属性 的 值 为 "on" > webview 容器 将 会 根据 属性 minwidth ， Minheight , maxwidth , 
和 maxheight 的 值 在 它们 之 间 自 适应 . RAL autosize 开启 的 时 候 这 个 约束 才 会 有 效 . 当 
autosize 开局 的 时 候 ， webview 容器 的 Size 只 能 在 上 面 那 四 个 属性 值 之 间 . 





nodeintegration 


<webview src="http://www.google.com/" nodeintegration></webview> 


如 果 设 置 了 这 个 属性 ， webview 中 的 guest page 将 整合 node， 并 且 拥 有 可 以 使 用 系统 底层 
的 资源 ， 例 如 require 和 process 


plugins 
<webview src="https://www.github.com/" plugins></webview> 

如 果 这 个 属性 的 值 为 "on" > webview 中 的 guest page 就 可 以 使 用 浏览 器 插件 。 
preload 


<webview src="https://www.github.com/" preload="./test.js"></webview> 


在 guest page 中 的 其 他 脚本 执行 之 前 预 加 载 一 个 指定 的 脚本 。 规 定 预 加 载 脚本 的 Ur| 须 如 
file: 或 者 asar: ， 因 为 它 在 是 guest page 中 通过 通过 require *P 命令 加 载 的 。 


guest page 没有 整合 node > %& +P AA IA ARAL + Node APIs ， 但 是 在 这 个 脚本 执 
完毕 时 ， 之 前 由 node 插 入 的 全 局 对 象 会 被 删除 。 


httpreferrer 


<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview> 


A guest page 设置 referrer URL ° 


useragent 


<webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Tri 
‘ — 
在 guest page 加 载 之 前 为 其 设置 用 户 代 理 。 如 果 页 面 已 经 加 载 了 ， 可 以 使 用 setUserAgent 
方法 来 改变 用 户 代理 。 








disablewebsecurity 


<webview src="https://www.github.com/" disablewebsecurity></webview> 
如 果 这 个 属性 的 值 为 "on" > guest page 会 禁用 web 安 全 控制 . 


partition 


<webview src="https://github.com" partition="persist :github"></webview> 
<webview src="http://electron.atom.io" partition="electron"></webview> 


为 page 设 置 sSession。 如 果 初 始 值 为 partition ,这 个 page 将 会 为 app 中 的 所 有 page 应 用 同 
一 个 持续 有 效 的 session。 如 果 没 有 persist: WA, 这 个 page 将 会 使 用 一 个 历史 session 

。 通 过 分 配 使 用 相同 的 partition ,所 有 的 page 都 可 以 分 享 相同 的 Session。 如 果 partition 
没有 设置 ， 那 app 将 使 用 默认 的 session. 


这 个 值 只 能 在 在 第 一 个 泻 染 进 程 之 前 设置 修改 ， 之 后 修改 的 话 会 无 效 并 且 抛 出 一 个 DOM 有 异常. 
allowpopups 
<webview src="https://www.github.com/" allowpopups></webview> 

如 果 这 个 属性 的 值 为 "on" ， 将 允许 guest page 打开 一 个 新 窗口 。 
blinkfeatures 


<webview src="https://www.github.com/" blinkfeatures="PreciseMemoryInfo, CSSVariables"></ 


本 








个 属性 的 值 为 一 个 用 过 号 分 隔 的 列表 ， 它 的 值 指 定 特 性 被 启用 。 你 可 以 从 
setFeatureEnabledFromString 元 数 找到 完整 的 支持 特性 。 


方法 
webview 的 方法 集合 : 


注意 : webview 元 素 必 须 在 使 用 这 
例如 


文 些 方法 之 前 加 载 完 毕 。 


webview.addEventListener("dom-ready", function() { 
webview.openDevTools(); 


3); 


<webview>.loadURL(url[, options] ) 


e url URL 


options Object ("T 2) 
o httpReferrer String -一 个 http 类 型 的 url 
userAgent String -用 于 发 起 请 求 的 用 户 代 理 . 
extraHeaders String - 额外 的 headers, 用 "\n" 分 陆 


加 载 Webview 中 的 url ， 


(0) 


o 


url 必须 包含 协议 前 级 ， 例 如 http:// 或 file:// 
<webview>.getURL( ) 


从 guest page 中 返回 url. 


<webview>.getTitle() 
从 guest page 中 返回 title. 
<webview>.isLoading( ) 
返回 一 个 guest page 是 否 仍 在 加 载 资 源 的 布尔 
<webview>.isWaitingForResponse( ) 


回 一 个 guest page 是 否 正在 等 待 page 的 主要 资源 做 出 回应 的 布尔 
<webview>.stop() 


停止 泻 染 . 


<webview>.reload( ) 

重新 加 载 guest page. 
<webview>.reloadIgnoringCache( ) 
忽视 缓存 ， 重 新 加 载 guest page. 
<webview>.canGoBack( ) 

返回 一 个 guest page 是 否 能 够 回 退 的 布尔 值 . 
<webview>.canGoForward( ) 

返回 一 个 guest page 是 否 能 够 前 进 的 布尔 值 . 
<webview> .canGoTooffset (offset) 


e offset Integer 


~ 


返回 一 个 guest page 是 否 能 够 前 进 到 offset 的 布尔 值 . 
<webview>.clearHistory( ) 

清除 导航 历史 . 
<webview>.goBack( ) 

guest page :&. 
<webview>.goForward( ) 

guest page 前 进 . 
<webview>.goToIndex(index) 
e index Integer 

guest page 导航 到 指定 的 绝对 位 置 . 
<webview>.goToOffset (offset) 


e offset Integer 


guest page 导航 到 指定 的 相对 位 置 . 


<webview>.isCrashed( ) 
返回 一 个 演 染 进程 是 否 崩 溃 的 布尔 值 . 
<webview>.setUserAgent (userAgent ) 
e userAgent String 
重新 设置 用 户 代 理 . 
<webview>.getUserAgent ( ) 
返回 用 户 代 理 名 字 ， 返 回 类 型 : string. 
<webview>.insertCSS(css) 


e css String 


插入 css. 


<webview>.executeJavaScript(code, userGesture, callback) 


e code String 
e userGesture Boolean - 默认 false. 
e callback Function (* 2) - 回调 元 数 . 


o result 


评估 code ， 如 果 userGesture 值 为 true ， 它 将 在 这 个 page 里 面 创建 用 户 手 势 . HTML APIS 
， 如 requestFullScreen , 它 需 要 用 户 响应 ， 那 么 将 自动 通过 这 个 参数 优化 . 


<webview>.openDevTools( ) 

A guest page 打开 开发 工具 调试 窗口 . 
<webview>.closeDevTools() 

A guest page 关闭 开发 工具 调试 窗口 . 
<webview>.isDevToolsOpened( ) 

返回 一 个 guest page 是 否 打开 了 开发 工具 调试 窗口 的 布尔 值 . 
<webview>.isDevToolsFocused( ) 


返回 一 个 guest page 是 否 聚 焦 了 开发 工具 调试 窗口 的 布尔 值 . 


<webview>.inspectElement(x, y) 


e x Integer 
e y Integer 


开始 检查 guest page & (x, y ) 位 置 的 元 素 . 


<webview>. inspectServiceworker () 


在 guest page 中 为 服务 人 员 打 开 开 发 工具 . 


<webview>.setAudioMuted (muted) 


e muted Boolean 设置 guest page 流畅 (muted). 


<webview>.isAudioMuted( ) 


返回 一 个 guest page 是 否 流畅 的 布尔 值 . 


<webview> .undo() 


在 page 中 编辑 执行 undo PA. 


<webview>.redo( ) 

在 page 中 编辑 执行 redo 命令 . 
<webview>.cut() 

在 page 中 编辑 执行 cut 命令 
<webview>.copy() 

在 page 中 编辑 执行 copy 命令 . 
<webview>.paste() 


在 page 中 编辑 执行 paste 命令 . 


<webview>.pasteAndMatchStyle() 


在 page 中 编辑 执行 pasteAndMatchStyle 命令 . 


<webview>.delete( ) 


在 page 中 编辑 执行 delete 命令 . 


<webview>.selectAll() 


在 page 中 编辑 执行 selectall 命令 . 


<wWebview> .unselect() 


在 page 中 编辑 执行 unselect 命令 . 


<webview>.replace(text) 


e text String 


在 page 中 编辑 执行 replace 命令 . 
<webview>.replaceMisspelling(text) 


e text String 


在 page 中 编辑 执行 replaceMisspelling 命令 . 


<webview>.insertText (text) 


e text String 


插入 文本 . 


<webview>.findInPage(text[, options] ) 


。 text String- 搜索 内 容 , 不 能 为 空 . 
e options Object (可 选 ) 
o forward Boolean - 向 前 或 向 后 , 默认 为 true. 
o findNext Boolean - 是 否 查找 的 第 一 个 结果 , RUA false. 
o matchcase Boolean - 是 否 区 分 大 小 写 , 默认 为 false. 
o wordstart Boolean - 是 否 只 查找 首 字母 . 默认 为 false. 
© medialcapitalAswordstart Boolean- 当 配 合 wordstart 的 时 候 , 接 受 一 个 文字 中 的 
匹配 项 ， 要 求 匹 配 项 是 以 大 写字 母 开 头 后 面 跟 小 号 字母 或 者 没有 字母 。 可 以 接受 一 
些 其 他 单词 内 部 匹配 , 默认 为 false. 


发 起 一 个 请 求 来 寻找 页 面 中 的 所 有 匹配 text 的 地 方 并 且 返 回 一 个 Integer 来 表示 这 个 请 求 
用 的 请 求 ld. 这 个 请 求 结果 可 以 通过 订阅 found-in-page 事件 来 取得 . 


<webview>.stopFindInPage(action) 


® action String - 指定 一 个 行为 来 接替 停止 <webview>.findInPage 请 求 . 
o clearSelection - 转变 为 一 个 普通 的 selection. 
© keepSelection - 清除 selection. 


o activateSelection - 聚焦 并 点 击 Selection node. 
使 用 action 停止 findInPage 请 求 . 
<webview>.print([options] ) 


打印 输出 webview 的 web page. 类 似 webcontents.print([options]) . 


<webview>.printToPDF(options, callback) 


以 pdf 格式 打印 输出 webview 的 web page. 类 似 


webContents.printToPDF(options, callback) . 


<webview>.send(channel[, argi][, arg2][, ...]) 


e channel String 
e arg (可 选 ) 


通过 channel 向 泻 染 进程 发 出 异步 消息 ， 你 也 可 以 发 送 任意 的 参数 。 泻 染 进程 通 
过 ipcRenderer 模块 监听 channel 事件 来 控制 消息 . 


例子 webContents.send. 


<webview>.sendInputEvent (event) 


e event Object 
向 page 发 送 输入 事件 . 


查看 webContents.sendlnputEvent 关于 event 对 象 的 相信 介绍 . 


<webview>.getWebContents() 


返回 和 这 个 webview 相关 的 WebContents. 
DOM 事件 
webview 可 用 下 面 的 DOM 事件 : 


Event: ‘load-commit' 


返回 : 


e url String 


e isMainFrame Boolean 


加 载 完成 触发 . 这 个 包含 当前 文档 的 导航 和 副 框 架 的 文档 加 载 ， 但 是 不 包含 异步 资源 加 载 . 


Event: 'did-finish-load' 


在 导航 加 载 完 成 时 触发 ， 也 就 是 tab 的 spinner 停 止 spinning， 并 且 加 载 事件 处 理 . 


Event: 'did-fail-load' 
Returns: 


e errorcode Integer 
e errorDescription String 


e validatedurRL String 


类 似 did-finish-load ， 在 加 载 失 败 或 取消 是 触发 ， 例 如 提出 window.stop() . 


Event: ‘did-frame-finish-load' 
返回 : 
e isMainFrame Boolean 


当 一 个 frame 完成 加 载 时 触发 . 


Event: ‘did-start-loading' 


开始 加 载 时 触发 . 


Event: ‘did-stop-loading' 


停止 家 在 时 触发 . 


Event: 'did-get-response-details' 
返回 : 


e status Boolean 
e newuRL String 


e originalurRL String 


e httpResponseCode Integer 
e requestMethod String 

è referrer String 

e headers Object 


当 获 得 返回 详情 的 时 候 触 发 . 


status 指示 socket 连接 来 下 载 资 源 . 


Event: did-get-redirect-request 
返回 : 


e olduURL String 
e newURL String 


e isMainFrame Boolean 


当 重 定向 请 求 资源 被 接收 的 时 候 触 发 . 


Event: 'dom-ready' 


当 指 定 的 ffame 文 档 加 载 完 毕 时 触发 . 


Event: ‘page-title-updated' 
返回 : 


e title String 
èe explicitset Boolean 


当 导 航 中 的 页 面 title 被 设置 时 触发 . title it CH BAH WRN explicitset X false. 


Event: 'page-favicon-updated' 
返回 : 
e favicons Array - Array of URLs. 


当 page 收 到 了 图 标 url| 时 触发 . 


Event: ‘enter-html-full-screen’' 


3 38 t HTML API 使 界面 进入 全 屏 时 触发 . 


Event: ‘leave-html-full-screen' 


当 通 过 HTML API 使 界面 退出 全 屏 时 触发 . 


Event: 'console-message' 
返回 : 


e level Integer 
e message String 
e line Integer 

e sourceId String 


当 客 户 端 输出 控制 台 信息 的 时 候 触 发 . 


下 面 示例 代码 将 所 有 信息 输出 到 内 置 控制 台 ， 没 有 考虑 到 输出 等 级 和 其 他 属性 


webview.addEventListener('console-message', function(e) { 
console.log('Guest page logged a message:', e.message); 


}); 


Event: 'found-in-page' 
返回 : 


e result Object 
© requestid Integer 
o finalupdate Boolean - 指明 下 面 是 否 还 有 更 多 的 回应 . 
o activeMatchOrdinal Integer (可 选 ) - 活动 匹配 位 置 
o matches Integer (optional) - 匹配 数量 . 
© selectionarea Object (optional) - 整合 第 一 个 匹配 域 . 


在 请 求 webview. findInPage 结果 有 效 时 触发 . 


webview.addEventListener('found-in-page', function(e) { 
if (e.result.finalUpdate) 
webview. stopFindInPage("keepSelection"); 


3); 


const rquestId = webview.findInPage("test"); 


Event: 'new-window' 
返回 : 


e url String 


o 


e frameName String 

e disposition String - 可 以 为 default , foreground-tab ，background-tab , new-window 
和 other . 

e options Object - 参数 应 该 被 用 作 创 建新 的 BrowserWindow . 


在 guest page 试图 打开 一 个 新 的 浏览 器 窗口 时 触发 . 


下 面 示例 代码 在 系统 默认 浏览 器 中 打开 了 一 个 新 的 url. 


webview.addEventListener('new-window', function(e) { 
require('electron').shell.openExternal(e.url); 


了 


Event: 'will-navigate’ 
返回 : 
e url String 


当 用 户 或 page 尝 试 开 始 导航 时 触发 . 它 能 在 window.location 变化 或 者 用 户 点 击 连接 的 时 候 
触发 . 


这 个 事件 在 以 APIS 编程 方式 开始 导航 时 不 会 触发 ， 例 如 <webview>.loaduRL 和 


<webview>.back . 


在 页 面 内 部 导航 跳 转 也 将 不 回 触 发 这 个 事件 ， 例 如 点 击 锚 链 接 或 更 新 window.location.hash . 
使 用 did-navigate-in-page 来 实现 页 内 跳 转 事件 . 


使 用 event.preventDefault() 并 不 会 起 什么 用 . 


Event: ‘did-navigate' 
返回 : 

e url String 
当 导 航 结束 时 触发 . 
在 页 面 内 部 导航 跳 转 也 将 不 回 触发 这 个 事件 ， 例 如 点 击 锚 链 接 或 更 新 window.location.hash . 
使 用 did-navigate-in-page 来 实现 页 内 跳 转 事件 . 
Event: ‘did-navigate-in-page’ 
返回 : 


e url String 


当 页 内 导航 发 生 时 触发 . 当 业 内 导航 发 生 时 ，page url 改 变 了 ， 但 是 不 会 跳出 page . 例如 在 锚 
链接 被 电击 或 DOM hashchange 事件 发 生 时 触发 . 


Event: ‘close’ 
在 guest page 试 图 关闭 自己 的 时 候 触 发 . 


下 面 的 示例 代码 指示 了 在 客户 端 试 图 关闭 自己 的 时 候 将 改变 导航 连接 为 about:blank . 


webview.addEventListener('close', function() { 
webview.src = ‘about:blank'; 


3); 


Event: ‘ipc-message' 
返回 : 


e channel String 
e args Array 


在 guest page 向 谋 入 页 发 送 一 个 异步 消息 的 时 候 触 发 . 


你 可 以 很 简单 的 使 用 sendToHost 方法 和 ipc-message 事件 在 guest page 和 KAW 


(embedder page) 之 间 通 信 : 


// In embedder page. 
webview.addEventListener('ipc-message', function(event) { 
console.log(event.channel) ; 
// 1 PGAneSS pong. 
3); 


webview.send('ping'); 


// In guest page 


var ipcRenderer = require('electron').ipcRenderer; 
ipcRenderer.on('ping', function() { 
ipcRenderer.sendToHost('pong'); 


3); 


Event: ‘crashed’ 


在 泻 染 进程 崩溃 的 时 候 触发 . 


Event: 'gpu-crashed' 


在 GPU 进程 崩溃 的 时 候 触 发 . 


Event: 'plugin-crashed' 
返回 : 


e name String 


e version String 


在 插件 进程 崩溃 的 时 候 触发 . 


Event: destroyed 
Je Fe A RA EY BY AR ABR 
Event: 'media-started-playing' 
在 媒体 准备 播放 的 时 候 触 发 . 


Event: 'media-paused' 


在 媒体 暂停 播放 或 播放 放 毕 的 时 候 触 发 . 


Event: did-change-theme-color 
在 页 面 的 主体 色 改 变 的 时 候 触发 . 在 使 用 meta 标签 的 时 候 这 就 很 常见 了 : 


<meta name='theme-color' content= '#ff0000 ' > 


Event: devtools-opened 


在 开发 者 工具 打开 的 时 候 触发 . 


Event: devtools-closed 


在 开发 者 工具 关闭 的 时 候 触发 . 


Event: ‘devtools-focused' 


在 开发 者 工具 获取 焦点 的 时 候 触 发 . 


window.open 44 


le window.open 来 创建 一 个 新 的 窗口 时 候 ， 将 


会 创 建 一 个 Browserwindow 的 实 
， 并且 将 返回 一 个 标识 ， 这 个 界面 通过 


竺 标识 来 对 这 个 新 的 窗口 进行 有 限 的 控制 


这 个 标识 对 传统 的 web 界 面 来 说 ， 通过 它 能 对 子 窗口 进行 有 限 的 功能 性 兼容 控制 . MEZA 
控制 这 个 窗口 ， 可 以 直接 创建 一 个 Browserwindow 


新 创建 的 Browserwindow 默认 为 继承 父 


窗口 的 属性 
中 设置 他 们 . 


， 想 重 写 属性 的 话 可 以 在 


features 


window.open(url[, frameName][, features] ) 


e url String 


frameName String (可 选 ) 
features String (可 选 ) 


创 建 一 个 新 的 window 并 且 返 回 一 个 BrowserWindowProxy 类 的 实例 . 


features 遵循 标准 浏览 器 的 格式 ， 但 是 每 个 feature 应 该 作为 Browserwindow 参数 的 一 个 
段 . 


window .opener . postMessage(message, targetOrigin) 


e message String 


e targetOrigin String 


通过 指定 位 置 或 用 * 来 代替 没有 明确 位 置 来 向 父 窗口 发 送信 息 . 


Class: BrowserWindowProxy 


BrowserwWindowProxy 由 window.open 创建 返回 ， 并 且 提供 了 对 子 窗口 的 有 限 功 能 性 控制 
BrowserWindowProxy.blur() 


子 窗 口 的 失去 焦点 . 


BrowserWindowProxy.close() 


强行 关闭 子 窗口 ， 忽 略 卸 载 事 件 . 


BrowserWindowProxy.closed 


在 子 窗 口 关闭 之 后 恢复 正常 . 
BrowserWindowProxy.eval (code) 
e code String 

评估 子 窗口 的 代码 . 
BrowserWindowProxy .focus( ) 


子 窗口 获得 焦点 (让 其 显示 在 最 前 ). 


BrowserWindowProxy.postMessage(message, targetOrigin) 


e message String 


e targetOrigin String 
通过 指定 位 置 或 用 * 来 代替 没有 明确 位 置 来 向 子 窗口 发 送信 息 . 


除了 这 些 方 法 ， 子 窗口 还 可 以 无 特性 和 使 用 单一 方法 来 实现 window.opener 对 象 . 


在 主 进程 内 可 用 的 模块 


app 


app 模块 是 为 了 控制 整个 应 用 的 生命 周期 设计 的 。 


下 面 的 这 个 例子 将 会 展示 如 何在 最 后 一 个 窗口 被 关闭 时 退出 应 用 : 


var app = require('app'); 

app.on('window-all-closed', function() { 
app.quit(); 

}); 


事件 列表 


app 对 象 会 触发 以 下 的 事件 : 


事件 : ‘will-finish-launching' 


当 应 用 程序 完成 基础 的 启动 的 时 候 被 触发 。 在 Windows 和 Linux 中 ， 
will-finish-launching 事件 与 ready 事件 是 相同 的 ; 在 OSX 中， 这 个 时 间 相 当 于 
NSApplication 中 的 applicationwillFinishLaunching 提示 。 你 应 该 经 常 在 这 里 为 
open-file 和 open-url 设置 监听 器 ， 并 局 动 崩溃 报告 和 自动 更 新 。 


在 大 多 数 的 情况 下 ， 你 应 该 只 在 ready 事件 处 理 器 中 完成 所 有 的 业务 


事件 : "ready' 


% Electron 完成 初始 化 时 被 触发 。 


事件 : "window-all-closed' 
当 所 有 的 窗口 都 被 关闭 时 触发 。 

这 个 时 间 仅 在 应 用 还 没有 退出 时 才能 触发 。 如 果 用 户 按 下 了 cmd + Q ， 或 者 开发 者 调用 了 
app.quit() ° Electron 将 会 先 尝试 关闭 所 有 的 窗口 再 触发 will-quit 事件 ， 在 这 种 情况 下 
window-all-closed 不 会 被 触发 。 
事件 : "before-quit' 
返回 : 


e event Event 


在 应 用 程序 开始 关闭 它 的 窗口 的 时 候 被 触发 。 调 用 event. preventDefault() 将 会 阻止 终止 应 
用 程序 的 默认 行为 。 
事件 : ‘will-quit' 
返回 : 
e event Event 


4 所 有 的 窗 口 已 经 被 关闭 ， 应 用 即将 退 出 时 被 触发 。 调 用 event. preventDefault() 将 会 阻止 
终止 应 用 程序 的 默认 行为 。 


你 可 以 在 window-all-closed 事件 的 描述 中 看 到 will-quit 事件 和 window-all-closed 事 
件 的 区 别 。 

事件 : "quit" 

返回 : 


e event Event 


e exitCode Integer 


当 应 用 程序 正在 退出 时 触发 。 


事件 : ‘open-file' OS X 
返回 : 


e event Event 
e path String 


当 用 户 想 要 在 应 用 中 打开 一 个 文件 时 触发 。 open-file 事件 常常 在 应 用 已 经 打开 并 且 系 统 想 
要 再 次 使 用 应 用 打开 文件 时 被 触发 。 open-file 也 会 在 一 个 文件 被 拖 入 dock 且 应 用 还 没有 
运行 的 时 候 被 触发 。 请 确认 在 应 用 启动 的 时 候 (其 至 在 _ ready 事件 被 触发 前 ) 就 对 
open-file 事件 进行 监听 ， 以 处 理 这 种 情况 。 


如 果 你 想 处 理 这 个 事件 ， 你 应 该 调用 event.preventDefault() ° 在 Windows & È P , 你 需要 
通过 解析 process.argv 来 获取 文件 路 径 。 

事件 : "open-url' OS X 

返回 : 


e event Event 
e url String 


当 用 户 想 要 在 应 用 中 打开 一 个 url 的 时 候 被 触发 。URL 格 式 必 须要 提前 标识 才能 被 你 的 应 用 打 


FF ee 


如 果 你 想 处 理 这 个 事件 ， 你 应 该 调用 event.preventDefault() ° 


事件 : ‘activate’ OS X 
返回 : 


e event Event 


e hasVisibleWwindows Boolean 


当 应 用 被 激活 时 触发 ， 常 用 于 点 击 应 用 的 dock 图 标的 时 候 。 


事件 : 'browser-window-blur' 
返回 : 


e event Event 
e window BrowserWindow 


当 一 个 BrowserWindow 失去 焦点 的 时 候 触 发 。 


事件 : 'browser-window-focus' 
返回 : 


e event Event 
e window BrowserWindow 


当 一 个 BrowserWindow 获得 焦点 的 时 候 触发 。 


事件 : 'browser-window-created 
返回 : 


e event Event 
e window BrowserWindow 


当 一 个 BrowserWindow 被 创建 的 时 候 触发 。 


事件 : 'certificate-error' 
返回 : 


e event Event 


e webContents WebContents 
e url String - URL 地 址 
e error String - 错误 码 
e certificate Object 
o data Buffer - PEM 编码 数据 
o issuerName String - 发 行者 的 公有 名 称 
e callback Function 


当 对 url 验证 certificate 证 书 失败 的 时 候 触 发 ， 如 果 需 要 信任 这 个 证 书 ， 你 需要 阻止 默 
认 行 为 event.preventDefault() 并 且 调用 callback(true) ° 


session.on('certificate-error', function(event, webContents, url, error, certificate, cal 
if (url == "https://github.com") { 
// 验证 逻辑 。 
event.preventDefault(); 
callback(true); 
} else { 
callback(false); 





e event Event 
e webContents WebContents 
e url String - URL 地 址 
e certificateList [Object] 
o data Buffer - PEM 编码 数据 
o issuerName String - 发 行者 的 公有 名 称 
e callback Function 


当 一 个 客户 端 认 证 被 请 求 的 时 候 被 触发 。 


url 指 的 是 请 求 客户 端 认 证 的 网 页 地 址 ， 调 用 callback 时 需要 传 入 一 个 证 书 列表 中 的 证 


需要 通过 调用 event.preventDefault() 来 防止 应 用 自动 使 用 第 一 个 证 书 进行 验证 。 如 下 所 


app.on('select-certificate', function(event, host, url, list, callback) { 
event.preventDefault(); 
callback(list[0]); 

}) 


事件 : login’ 


e event Event 
e webContents WebContents 
e request Object 
© method String 
o url URL 
o referrer URL 
e authInfo Object 
o isProxy Boolean 
© scheme String 
o host String 
o port Integer 
o realm String 
e callback Function 


当 webcontents 要 做 进行 一 次 HTTP 登陆 验证 时 被 触发 。 


默认 情况 下 ，Electron 会 取消 所 有 的 验证 行为 ， 如 果 需 要 重 写 这 个 行为 ， 你 需要 用 
event.preventDefault() 来 阻止 默认 行为 并 且 用 callback(username, password) 来 进行 验 
证 。 


app.on('login', function(event, webContents, request, authInfo, callback) { 
event.preventDefault(); 
callback('username', 'secret'); 


}) 


事件 : 'gpu-process-crashed' 


当 GPU 进程 前 溃 时 触发 。 


方法 列表 
app 对 象 拥 有 以 下 的 方法 : 
请 注意 有 的 方法 只 能 用 于 特定 的 操作 系统 。 


app.quit() 


试图 关 掉 所 有 的 窗口 。 before-quit 事件 将 会 最 先 被 触发 。 如 果 所 有 的 窗口 都 被 成 功 关闭 
J > will-quit 事件 将 会 被 甬 发 ， 默 认 下 应 用 将 会 被 关闭 。 


这 个 方法 保证 了 所 有 的 beforeunload 和 unload 事件 处 理 器 被 正确 执行 。 假 如 一 个 窗口 的 
beforeunload 事件 处 理 器 返回 false ， 那 么 整个 应 用 可 能 会 取消 退出 。 


app.hide() OS X 


隐藏 所 有 的 应 用 窗口 ， 不 是 最 小 化 . 


app.show() OSX 


隐藏 后 重新 显示 所 有 的 窗口 ， 不 会 自动 选中 他 们 。 


app.exit(exitCode) 
© exitCode 整数 
带 着 exitCode 退出 应 用 . 


所 有 的 窗口 会 被 立刻 关闭 ， 不 会 询问 用 户 。 before-quit 和 will-quit 这 2 个 事件 不 会 被 触 
发 


app.getAppPath() 


返回 当前 应 用 所 在 的 文件 路 径 。 


appb.getPath(name ) 


e name String 
返回 一 个 与 name 参数 相关 的 特殊 文件 夹 或 文件 路 径 。 当 失败 时 抛 出 一 个 Error 。 
你 可 以 通过 名 称 请 求 以 下 的 路 径 : 


e home 用 户 的 home 文件 夹 ( 主 目 录 ) 
© appData 当前 用 户 的 应 用 数据 文件 夹 ， 上 默认 对 应 : 
o %APPDATA% Windows 中 
© $XDG_CONFIG_HOME Or ~/.config Linux 中 
o =6©~/Library/Application Support OS X 中 
@ USerData 储存 你 应 用 程序 设置 文件 的 CHK Rice appData 文件 夹 附加 应 用 的 名 称 
e temp 临时 文件 夹 
e exe 当前 的 可 执行 文件 
e module libchromiumcontent Æ 
e desktop 当前 用 户 的 桌面 文件 夹 
e documents 用 户 文档 目录 的 路 径 
e downloads 用 户 下 载 目录 的 路 径 . 


e music 用户 音乐 目录 的 路 径 . 
e pictures 用 户 图 片 目录 的 路 径 . 
e videos 用 户 视频 目录 的 路 径 . 


app.setPath(name, path) 


e name String 
e path String 


重 写 某 个 name 的 路 径 为 path ， path 可 以 是 一 个 文件 夹 或 者 一 个 文件 ， 这 个 和 name 的 
类 型 有 关 。 如 果 这 个 路 径 指向 的 文件 夹 不 存在 ， 这 个 文件 夹 将 会 被 这 个 方法 创建 。 如 果 错 误 
则 会 抛 出 Error ° 


name 参数 只 能 使 用 app.getPath 中 定义 过 name ° 


默认 情况 下 ， 网 页 的 cookie 和 缓存 都 会 储存 在 userpata XR o 如果 你 想 要 改变 这 个 位 
置 ， 你 需要 在 app 模块 中 的 ready 事件 被 触发 之 前 重 写 userdata 的 路 径 。 


app.getVersion() 


返回 加 载 应 用 程序 的 版 本 8 如 果 应 用 程序 的 package.json 文件 中 没有 写 版 本 号 ， 将 会 返回 
当前 包 或 者 可 执行 文件 的 版 本 。 


app. getName() 


返回 当前 应 用 程序 的 package.json 文件 中 的 名 称 。 


由 于 npm 的 命名 规则 ， 通 常 name 字段 是 一 个 短 的 小 写字 符 串 。 但 是 应 用 名 的 完整 名 称 通常 
是 首 字 母 大 写 的 ý 你 应 该 单独 使 用 一 个 productName 字段 用 于 表示 你 的 应 用 程序 的 完整 名 
称 。Electron 会 优先 使 用 这 个 字段 作为 应 用 名 。 


app.setName(name) 
e name String 
重 写 当 前 应 用 的 名 字 
app.getLocale() 


返回 当前 应 用 程序 的 语言 。 


app.addRecentDocument(path) OS X Windows 


e path String 


在 最 近 访 问 的 文档 列表 中 添加 path ° 
这 个 列表 由 操作 系统 进行 管理 。 在 Windows 中 您 可 以 通过 任务 条 进行 访问 ， 在 OS X 中 你 可 


以 通过 dock 菜单 进行 访问 。 


app.clearRecentDocuments() OS X Windows 


清除 最 近 访 问 的 文档 列表 。 


app.setUserTasks(tasks) Windows 

e tasks [Task] -一 个 由 Task 对 象 构成 的 数组 
将 tasks 添加 到 Windows 中 JumpList 功能 的 Tasks 分 类 中 。 
tasks 中 的 task 对 象 格式 如 下 : 


Task Object 
© program String - 执行 程序 的 路 径 ， 通 常 你 应 该 说 明 当 前 程序 的 路 径 为 
process.execPath 字段 。 
e arguments String- 当 program 执行 时 的 命令 行 参 数 。 
e title String - JumpList 中 显示 的 标题 。 
e description String - 对 这 个 任务 的 描述 。 


e iconpath pr - JumpList 中 显示 的 图 标的 绝对 路 径 ， 可 以 是 一 个 任意 包含 一 个 图 标的 
资源 文件 。 通 常 来 说 ， 你 可 以 通过 指明 process.execPath 来 显示 程序 中 7 图 标 。 
e iconIndex ees 图 标 文 件 中 的 采用 的 图 标 位 置 。 如 果 一 个 图 标 文件 包括 了 多 个 图 
标 ， 就 需要 设置 这 个 值 以 确定 使 用 的 是 哪 一 个 图 标 。 如 果 这 个 图 标 文件 中 只 包含 一 个 图 
标 ， 那 么 这 个 值 为 0。 
app .allowNTLMCredentialsForAl1Domains (allow) 
èe allow Boolean 
动态 设置 是 否 总 是 为 HTTP NTLM A Negotiate 认证 发 送 证 书 。 通 常 来 说 ，Electron 只 会 对 本 
络 eRe et 的 计算 机 ) 发 送 NTLM Kerberos mer 。 但 是 假如 网 络 设置 
得 不 太 好 ， 可 能 这 个 自动 探测 会 失效 ， 所 以 你 可 以 通过 这 个 接口 自 定 义 Electron 对 所 有 URL 


ae o 
app.makeSingleInstance(callback ) 


e callback Function 


这 个 方法 可 以 让 你 的 应 用 在 同一 时 刻 最 多 只 会 有 一 个 实例 ， 否 则 你 的 应 用 可 以 被 运行 多 次 并 


产生 多 个 实例 。 你 可 以 利用 这 个 接口 保证 只 有 一 个 实例 正 常 运 行 ， 其 余 的 实例 全 部 会 被 终止 
并 退出 。 


如 果 多 个 实例 同时 运行 ， 那 么 第 一 个 被 运行 的 实例 中 callback 会 以 

callback(argv, workingDirectory) 的 形式 被 调用 。 其 余 的 实例 会 被 终止 。 argv 是 一 个 包 
含 了 这 个 实例 的 命令 行 参数 列表 的 数组 ， workingpirectory 是 这 个 实例 目前 的 运行 目录 。 通 
常 来 说 ， 我 们 会 用 通过 将 应 用 在 主屏 幕 上 激活 ， 并 且 取 消 最 小 化 ， 来 提醒 用 户 这 个 应 用 已 经 
被 打开 了 。 


在 app 的 ready 事件 后 ，callback 才 有 可 能 被 调用 。 


如 果 当 前 实例 为 第 一 个 实例 ， 那 么 在 这 个 方法 将 会 返回 false 来 保证 它 继续 运行 。 否 则 将 会 
返回 true 来 让 它 立 刻 退 出 。 


在 OSX 中 ， 如 果 用 户 通 过 Finder> open-file 或 者 mA 打开 应 用 ， 系 统 会 强制 确保 
只 有 一 个 实例 在 运行 。 但 是 如 果 用 户 是 通过 命令 行 打开 ， 这 个 系统 机 制 会 被 忽略 ， 所 以 你 仍 
然 需 要 靠 这 个 方法 来 保证 应 用 为 单 实例 运行 的 。 


下 面 是 一 个 简单 的 例子 。 我 们 可 以 通过 这 个 例子 了 解 如 何 确保 应 用 为 单 实例 运行 状态 。 


var myWindow = null; 


var Som el = app. ene a ee ee workingDirectory) { 
// 3A-*E 行 的 时 候 ， 这 里 将 会 被 调用 ， 我 们 需要 激活 应 用 的 窗口 
if (uncon) t 
if (myWindow.isMinimized()) myWindow.restore(); 
myWindow.focus(); 


return true; 


}); 
// 这 个 实例 是 多 余 的 实例 ， 需 要 退出 
if (shouldQuit) { 


app.quit(); 
return; 


} 


// 创建 窗口 、 继 续 加 载 应 用 、 应 用 逻辑 等 
app.on('ready', 人 E 
}); 


app.setAppUserModelId(id) Windows 
e id String 


改变 当前 应 用 的 Application User Model ID A id . 


app.isAeroGlassEnabled() Windows 


如 果 DWM composition(Aero Glass) 启用 了 ， 那 么 这 个 方法 会 返回 true? She 
false 。 你 可 以 用 这 个 方法 来 决定 是 否 要 开局 透明 窗口 特效 ， 因 为 如 果 用 户 没 开 尼 DWM， 那 
么 透明 窗 口 特效 是 无 效 的 。 


举 个 例子 : 


let browserOptions = {width: 1000, height: 800}; 


// 只 有 平台 支持 的 时 候 才 使 用 透明 窗口 


if (process.platform !== 'win32' || app.isAeroGlassEnabled()) { 
browserOptions.transparent = true; 
browserOptions.frame = false; 


} 


// 创建 窗口 
win = new BrowserWindow(browserOptions) ; 


// 转 到 某 个 网 页 
If (browserOptions.transparent) { 
win. loadURL('file://' + _ dirname + '/index.html'); 
} else { 
// 没有 透明 特效 ， 我 们 应 该 用 某 个 只 包含 基本 样式 的 替代 解决 方案 
win. AAR file: //' + _dirname + '/fallback.html'); 
} 


app.commandLine.appendSwitch(switch[, value] ) 

通过 可 选 的 参数 value 给 Chromium 中 添加 一 个 命令 行 开 关 。 

注意 这 个 方法 不 会 影响 process.argy ， 我 们 通常 用 这 个 方法 控制 一 些 底层 Chromium 行 
为 。 

app.commandLine.appendArgument (value) 

给 Chromium 中 直接 添加 一 个 命令 行 参 数 ， 这 个 参数 value 的 引号 和 格式 必须 正确 。 


注意 这 个 方法 不 会 影响 process.argv ° 


app.dock.bounce([type]) OSX 


e type String - THAR? 可 以 是 critical 或 informational 。 默 认为 


informational ° 


当 传 入 的 是 _ critical it > dock 中 的 应 用 将 会 开始 弹跳 ， 直 到 这 个 应 用 被 激活 或 者 这 个 请 求 
被 取消 。 


当 传 入 的 是 informational 时 ，dock 中 的 图 标 只 会 弹跳 一 秒 钟 。 但 是 ， 这 个 请 求 仍 然 会 激 
直到 应 用 被 激活 或 者 请 求 被 取消 。 


这 个 方法 返回 的 返回 值 表 示 这 个 请 求 的 ID。 


app.dock.cancelBounce(id) OS X 
e id Integer 

取消 这 个 id 对 应 的 请 求 。 
app.dock.setBadge(text) OS X 
e text String 

设置 应 用 在 dock 中 显示 的 字符 串 。 
app.dock.getBadge() OS X 


返回 应 用 在 dock 中 显示 的 字符 串 。 


app.dock.hide() OS X 


隐藏 应 用 在 dock 中 的 图 标 。 


app.dock.show() OS X 


显示 应 用 在 dock 中 的 图 标 。 


app.dock.setMenu(menu) OS X 


e menu Menu 


设置 应 用 的 dock 菜单 . 


app.dock.setIcon(image) OS X 


e image Nativelmage 


设置 应 用 在 dock 中 显示 的 图 标 。 


autoUpdater 


这 个 模块 提供 了 一 个 到 squirrel 自动 更 新 框架 的 接口 。 


平台 相关 的 提示 

虽然 autoupdater 模块 提供 了 一 套 各 平台 通用 的 接口 ， 但 是 在 每 个 平台 间 依 然 会 有 一 些微 小 
的 差异 。 

OS X 


在 OSX 上， autoupdater 模块 依靠 的 是 内 置 的 ln Mac， 这 意味 着 你 不 需要 依靠 其 他 
的 设置 就 能 使 用 。 关 于 更 新 服务 器 的 配置 ， 你 可 以 通过 阅读 Server Support 这 篇 文章 来 了 
解 。 


Windows 


在 Windows 上 ， 你 必须 使 用 安装 程序 将 你 的 应 用 装 到 用 户 的 计算 机 上 ， 所 以 比较 推荐 的 方法 
是 用 grunt-electron-installer 这 个 模块 来 自动 生成 一 个 Windows 安装 向 导 。 


Squirrel 自动 生成 的 安装 向 导 会 生成 一 个 带 Application User Model ID 的 快捷 方式 。 
Application User Model ID 的 格式 是 com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE ， 比 
如 像 com.squirrel.slack.Slack 和 com.squirrel.code.Code 这 样 的 。 你 应 该 在 自己 的 应 用 中 
使 用 app.setAppUserModelid 方法 设置 相同 的 API， 不 然 Windows 将 不 能 正确 地 把 你 的 应 用 
固定 在 任务 栏 上 。 


服务 器 端的 配置 和 OS X 也 是 不 一 样 的 ， 你 可 以 阅读 Squirrel. Windows 这 个 文档 来 获得 详细 


Linux 


Linux 下 没有 任何 的 自动 更 新 支持 ， 所 以 我 们 推荐 用 各 个 Linux 发 行 版 的 包 管 理 器 来 分 发 你 的 


事件 列表 
autoUpdater 对 象 会 触发 以 下 的 事件 : 


事件 : ‘error’ 


返回 : 
e error Error 


当 更 新 发 生 错误 的 时 候 触 发 。 


事件 : 'checking-for-update' 


当 开 始 检 查 更 新 的 时 候 触 发 。 


事件 : ‘update-available' 


当 发 现 一 个 可 用 更 新 的 时 候 触 发 ， 更 新 包 下 载 会 自动 开始 。 


事件 : 'update-not-available' 


当 没 有 可 用 更 新 的 时 候 触 发 。 


事件 : 'update-downloaded' 


e event Event 

èe releaseNotes String - 新 版 本 更 新 公告 
e releaseName String - 新 的 版 本 号 

e releasepate Date - 新 版 本 发 布 的 日 期 
e updateurRL String - 更 新 地 址 


在 更 新 下 载 完 成 的 时 候 触 发 。 

在 Windows 上 只 有 releaseName 是 有 效 的 。 
方法 列表 

autoUpdater 对 象 有 以 下 的 方法 : 


autoUpdater .setFeedURL(url1) 


e url String 


设置 检查 更 新 的 url ， 并 且 初 始 化 自动 更 新 。 这 个 url 一 旦 设置 就 无 法 更 改 。 


autoUpdater .checkForUpdates( ) 


向 服务 端 查询 现在 是 否 有 可 用 的 更 新 。 在 调用 这 个 方法 之 前 ， 必 须要 先 调 用 setFeedURL ° 


autoUpdater .quitAndInstall() 


在 下 载 完成 后 ， 重 局 当前 的 应 用 并 且 安 装 更 新 。 这 个 方法 应 该 仅 在 update-downloaded 事件 
触发 后 被 调用 。 


BrowserWindow 


BrowserWindow 类 让 你 有 创建 一 个 浏览 器 窗口 的 权力 。 例 如 : 


// 
fis 


In the main process. 
const BrowserWindow = require('electron').BrowserWindow; 


Li SONG 
const BrowserWindow = require('electron').remote.BrowserWindow; 


a n 


the renderer process. 


var win = new BrowserWindow({ width: 800, height: 600, show: false }); 
win.on('closed', function() { 
win = null; 


3); 


win. loadURL('https://github.com'); 
win.show(); 


你 也 可 以 不 通过 chrome 创 建 窗 口 ， 使 用 Frameless Window API. 


Class: BrowserWindow 


Browserwindow 是 一 个 EventEmitter. 


通过 options 可 以 创建 一 个 具有 本 质 属性 的 BrowserWindow 


new BrowserWindow( [options ] ) 


options Object 


o 


o 


o 


width Integer - 窗口 宽度 ,单位 像素 . 默认 是 B800. 
height Integer- 窗口 高 度 ,单位 像素 . 默认 是 ooo. 

x Integer - 窗口 相对 于 屏幕 的 左 偏 移 位 置 .默认 居中 . 

y Integer - 窗口 相对 于 屏幕 的 顶部 偏 移 位 置 .默认 居中 . 


useContentSize Boolean - width 和 height 使 用 web 网 页 size, RBA KE 


的 size 应 该 包括 窗口 框架 的 size， 稍 微 会 大 一 点 ， 黑 认为 false. 
center Boolean - 窗口 屏幕 居中 . 

minwidth Integer- 窗口 最 小 宽度 ， 默 认为 o0. 

minHeight Integer- 窗口 最 小 高 度 ， 默 认为 o. 
maxwidth Integer- 窗口 最 大 宽度 ， 上 默认 无 限制 . 
maxHeight Integer- 窗口 最 大 高 度 ， 默 认 无 限制 . 


resizable Boolean - 是 否 可 以 改变 窗口 size， 默 认为 true. 

movable Boolean - 窗口 是 否 可 以 拖 动 .在 Linux 上 无 效 . 默认 为 true. 
minimizable Boolean - 窗口 是 否 可 以 最 小 化 .在 Linux 上 无 效 . 默认 为 true . 
maximizable Boolean - 窗口 是 否 可 以 最 大 化 .在 Linux 上 无 效 . 默认 为 true. 


o closable Boolean - 窗口 是 否 可 以 关闭 . 在 Linux 上 无 效 . 默认 为 true. 

o alwaysontop Boolean - 窗口 是 否 总 是 显示 在 其 他 窗口 之 前 . 在 Linux 上 无 效 . 默认 为 
false . 

o fullscreen Boolean - 窗口 是 否 可 以 全 屏幕 . 当 明 确 设置 值 为 When false ， 全 屏 
化 按钮 将 会 隐藏 ， 在 OS X 将 禁用 . 默认 false . 

o fullscreenable Boolean - Æ OS X 上 ， 全 屏 化 按钮 是 否 可 用 ， 默 认为 true. 

o skipTaskbar Boolean - 是 否 在 人 物 栏 中 显示 窗口 .默认 是 false . 

o kiosk Boolean - kiosk 方式. 默认 为 false . 

o title String - 窗口 默认 title. 默认 "Electron" . 

o icon a 窗口 图 标 , 如 果 不 设置 ， 窗 口 将 使 用 可 用 的 默认 图 标 . 

o show Boolean - 窗口 创建 的 时 候 是 否 显示 . 默认 为 true. 

o frame Boolean -指定 false 来 创建 一 个 Frameless Window. 默认 为 true. 

o acceptFirstMouse Boolean - 是 否 允 许 单 击 Web view 来 激活 窗口 . 默认 为 false. 

© disableAutoHidecursor Boolean - 当 typing 时 是 否 隐 藏 息 标 .默认 false . 

© autoHideMenuBar Boolean - 除非 点 击 alt ， 否 则 隐藏 菜单 栏 .默认 为 false. 

© enableLargerthanScreen Boolean - 是 否 允 许 允 许 改 变 窗口 大 小 大 于 屏幕 . 默认 是 
false . 

o backgroundcolor String -窗口 的 background color 值 为 十 六 进 制 ,如 #66cD66 或 
#FFF 或 ，#89FFFFFF (支持 透明 度 ). 默认 为 在 Linux 和 Windows #000 (黑色 ) ， 
Mac 上 为 #FFF (或 透明 ). 

o hasShadow Boolean- 窗口 是 否 有 阴影 . 只 在 OSX 上 有 效 . 默认 为 true. 

o darkTheme Boolean -为 窗口 使 用 dark 主题 , 只 在 一 些 拥有 GTK+3 桌面 环境 上 有 效 . 
默认 为 false. 

o transparent pooled -窗口 i. RUA false. 

o type String - 窗口 type, 默认 普通 窗口 .下 面 查 看 更 多 . 

o titleBarStyle String - 窗口 标题 栏 样式 . 下 面 查看 更 多 . 

o webPreferences Object- 设置 界面 特性 . 下 面 查看 更 多 . 


type 的 值 和 效果 不 同 平台 展示 效果 不 同 ， 有 具体 : 


e Linux, 可 用 值 为 desktop, dock ，toolbar , splash , notification . 
e OSX, 可 用 值 为 desktop , textured . 
o textured ype: 添加 金属 梯度 EXA ( NSTexturedBackgroundWindowMask ). 
o desktop 设置 窗口 在 桌面 背景 窗口 水 平 ( kcedesktopWindowlevel - 1). 注意 桌面 窗 
口 不 可 聚焦 , 不 可 不 支持 键盘 和 鼠标 事件 , 但 是 可 以 使 用 globalshortcut 来 解决 输入 


问题 . 
titleBarstyle 只 在 OS X 10.10 Yosemite 或 更 新 版 本 上 支持 . 可 用 值 : 


e default 以 及 无 值 , 显示 在 Mac 标题 栏 上 为 不 透明 的 标准 灰色 . 
© hidden 隐藏 标题 栏 ， 内 容 充满 整个 窗口 , 然后 它 依然 在 左上 角 ， 仍 然 受 标准 窗口 控制 . 
e hidden-inset 主体 隐藏 ， 显 示 小 的 控制 按钮 在 窗口 边缘 . 


webPreferences 参数 是 个 对 象 ， 它 的 属性 


nodeIntegration Boolean - 是 否 完整 支 持 node. 默认 为 true . 

preload String - 界面 的 其 它 脚 本 运行 之 前 aaa 一 个 指定 脚本 . 这 个 脚本 将 一 直 可 以 
使 用 node APIs 无 论 node integration 是 否 开 启 . 脚本 路 径 为 绝对 路 径 . 当 node 
integration 关闭 , 预 加 载 的 脚本 将 从 全 局 范围 he 入 node 的 全 局 引用 标志 . 查看 例子 
here. 

session Session - 设置 界面 session. a A re 4 A 略 session 对 象 ， 也 可 用 partition 
KRG, 它 接受 一 个 partition 字符 串 . 当 同 时 使 用 session 和 partition, session 优先 
级 更 高 . 默认 使 用 默认 session. 

partition String - 通过 session 的 partition 字 符 串 来 设置 界面 session. 如 果 partition 
以 persist: 开头 ， 这 个 界面 将 会 B 为 所 有 界面 使 用 相 同 的 partition . 如 果 没 有 

persist: 前 A, 界面 使 用 历史 session. 通过 分 享 同 一 个 partition , 所 有 界面 使 用 相 同 
的 Session. 默认 使 用 默认 session. 

zoomFactor Number- 界 面 默 认 缩 放 值 ，3.0 表示 300%. Rik 1.0. 

javascript Boolean - 开启 javascript 支 持 . AN true . 

webSecurity Boolean - 当 设 置 为 false , 它 将 禁用 相同 地 方 的 规则 (通常 测试 服 ), 并 且 
如 果 有 2 个 非 用 户 设置 的 参数 ， 就 设置 allowDisplayingInsecureContent 和 
allowRunningInsecureContent 的 值 为 true. 默认 为 true. 
allowDisplayingInsecureContent Boolean -允许 一 个 使 用 https 的 界面 来 展示 由 http 
URLs 传 过 来 的 资源 . 默认 false . 

allowRunningInsecureContent Boolean - Boolean -允许 一 个 使 用 https 的 界面 来 泻 染 由 
http URLs 提交 的 html,css,javascript. 默认 为 false . 

images Boolean - 开启 图 片 使 用 支持 . 默认 true. 

textAreasAreResizable Boolean - textArea 可 以 编辑 . 默认 为 true. 

webgl Boolean - 开启 WebGL 支持 . 默认 为 true. 

webaudio Boolean - 开启 WebAudio 支持 . 默认 为 true. 

plugins Boolean - 是 否 开局 插件 支持 . 默认 为 false . 

experimentalFeatures Boolean - 开启 Chromium 的 可 测试 特性 . 默认 为 false. 
experimentalcanvasFeatures Boolean - 开启 Chromium 的 canvas 可 测试 特性 . 默认 为 
false . 

directwrite Boolean - 开启 窗口 的 DirectWrite font 浑 染 系统 . 默认 为 true. 
blinkFeatures String - 以 k 分 隔 的 特性 列 Š, 如 CSSVariables, KeyboardEventkKey . 被 支 
持 的 所 有 特性 可 在 setFeatureEnabledFromString 中 找到 . 

defaultFontFamily Object - 设置 font-family 默认 字体 . 

o standard String - 默认 为 Times New Roman . 

o serif String - 默认 为 Times New Roman . 

o sansSerif String- AAA arial . 

O monospace String - 默认 为 courier New . 

defaultFontSize Integer- 默认 为 16. 

defaultMonospaceFontSize Integer - 默认 为 13. 


e minimumFontSize Integer- 默认 为 o. 
e defaultEncoding String- 默认 为 Iso-8859-1 . 


事件 


Browserwindow 对 象 可 触发 下 列 事 件 : 


注意 : 一 些 事件 只 能 在 特定 os 环境 中 和 触发， 已 经 尽 可 能 地 标 出 . 


Event: 'page-title-updated' 
返回 : 
e event Event 


当 文 档 改变 标题 时 触发 ,使 用 event.preventDefault() 可 以 阻止 原 窗口 的 标题 改变 . 


Event: ‘close’ 
返回 : 

e event Event 
在 窗口 要 关闭 的 时 候 触 发 . 它 在 DOM 的 beforeunload and unload 事件 之 前 触发 .使 用 
event.preventDefault() 可 以 取消 这 个 操作 
通常 你 想 通过 beforeunload 处 理 器 来 决定 是 否 关 闭 窗口 ， 但 是 它 也 会 在 窗口 重 载 的 时 候 被 触 
发 . 在 Electron 中 ， 返 回 一 个 空 的 字符 串 或 false 可 以 取消 关闭 .例如 : 


window.onbeforeunload = function(e) { 
console.log('I do not want to be closed'); 


// Unlike usual browsers, in which a string should be returned and the user is 
// prompted to confirm the page unload, Electron gives developers more options. 
// Returning empty string or false would prevent the unloading now. 


// You can also use the dialog API to let the user confirm closing the application. 
e.returnValue = false; 


Event: ‘closed’ 


当 窗 口 已 经 关闭 的 时 候 触 发 . 当 你 接收 到 这 个 事件 的 时 候 ， 你 应 当 删 除 对 已 经 关闭 的 窗口 的 引 
用 对 象 和 避免 再 次 使 用 它 . 


Event: 'unresponsive' 


在 界面 卡 死 的 时 候 触 发 事件 . 


Event: 'responsive' 


在 界面 恢复 卡 死 的 时 候 触 发 . 


Event: ‘blur’ 


在 窗口 失去 焦点 的 时 候 触 发 . 


Event: ‘focus’ 


在 窗口 获得 焦点 的 时 候 触发 . 


Event: ‘maximize’ 


在 窗口 最 大 化 的 时 候 触发 . 


Event: ‘'unmaximize' 


在 窗口 退出 最 大 化 的 时 候 触发 . 


Event: ‘minimize’ 


在 窗口 最 小 化 的 时 候 触发 . 


Event: ‘restore’ 


在 窗口 从 最 小 化 恢复 的 时 候 触发 . 


Event: ‘resize’ 


在 窗口 Size 改变 的 时 候 触发 . 


Event: ‘move’ 
在 窗口 移动 的 时 候 触 发 . 


注意 : 在 OSX 中 别名 为 moved . 


Event: 'moved' OS X 


在 窗口 移动 的 时 候 触发 . 


Event: ‘enter-full-screen’' 


在 的 窗口 进入 全 屏 状 态 时 候 触发 . 


Event: ‘leave-full-screen' 


在 的 窗口 退出 全 屏 状 态 时 候 触 发 . 


Event: ‘enter-html-full-screen' 


在 的 窗口 通过 html api 进入 全 屏 状 态 时 候 触 发 . 


Event: ‘leave-html-full-screen 


在 的 窗口 通过 html api 退出 全 屏 状 态 时 候 触发 . 


Event: 'app-command' Windows 


在 请 求 一 个 App Command.aspx) 的 时 候 触 发 . 典型 的 是 键盘 媒体 或 浏览 器 命令 , Windows £49 
"Back" 按钮 用 作 和 鼠标 也 会 触发 . 


SONS eo ue a comand TUNE ELONE oe) { 
JACK ne k 1 
if (el = === rasan backward" 88 EENE webContents. Ce { 
someWindow.webContents.goBack(); 


} 
H); 
Event: 'scroll-touch-begin' OS X 
在 滚动 条 事件 开始 的 时 候 触 发 . 
Event: 'scroll-touch-end' OS X 
在 滚动 条 事件 结束 的 时 候 触 发 . 
方法 


BrowserWindow 对 有 象 有 如 下 方法 : 


BrowserWindow. getAllWindows( ) 
返回 一 个 所 有 已 经 打开 了 窗口 的 对 象 数 组 . 

BrowserWindow. getFocusedWindow( ) 
返回 应 用 当前 获得 焦点 窗口 ,如 果 没 有 就 返回 pull. 
BrowserWindow.fromwebContents(webContents) 
e webContents WebContents 
根据 webcontents 查找 窗口 . 

Browserwindow.fromId (id) 

e id Integer 
根据 id 查找 窗口 

BrowserWindow. addDevToolsExtension(path) 

e path String 
添加 位 于 path 的 开发 者 工具 栏 扩展 ,并 且 返 回 扩 展 项 的 名 字 . 
这 个 扩展 会 被 添加 到 历史 ， 所 以 只 需要 使 用 这 个 API 一 次 ， 这 个 api 不 可 用 作 编 程 使 用 . 
BrowserWindow. removeDevToolsExtension(name ) 


e name String 


删除 开发 者 工具 栏 名 为 name 的 扩展 . 


实例 属性 


使 用 new Browserwindow 创建 的 实例 对 象 ， 有 如 下 属性 : 


// In this example 


var win = new BrowserWindow({ width: 800, height: 600 }); 


win.webContents 


这 个 窗口 的 webcontents 对 象 ， 所 有 与 界面 相关 的 事件 和 方法 都 通过 它 完 成 的 . 


查看 webcontents documentation 的 方法 和 事件 . 
win.id 


窗口 的 唯一 id. 


实例 方法 

使 用 new Browserwindow 创建 的 实例 对 和 象 ， 有 如 下 方法 : 

注意 : 一 些 方法 只 能 在 特定 os 环境 中 调用 ， 已 经 尽 可 能 地 标 出 . 
win.destroy() 


强制 关闭 窗口 ，unload and beforeunload 不 会 触发 ， 并 且 close 也 不 会 触发 , 但 是 它 保 证 
了 closed 触发 . 


win.close() 


尝试 关闭 窗口 ， 这 与 用 户 点 击 关闭 按钮 的 效果 一 样 . 虽然 网 页 可 能 会 取消 关闭 ， 查 看 close 
event. 


win.focus() 


窗口 获得 焦点 . 


win.isFocused() 


返回 boolean, 窗口 是 否 获得 焦点 . 


win. show( ) 


展示 并 且 使 窗口 获得 焦点 . 


win .showInactive() 


win.hide() 


隐藏 窗口 . 


win.isVisible() 


返回 boolean, 窗口 是 否 可 见 . 


win.maximize() 


窗口 最 大 化 . 

win. unmaximize( ) 
取消 窗口 最 大 化 . 
win.isMaximized() 


返回 boolean, 窗口 是 否 最 大 化 . 


win.minimize() 
窗口 最 小 化 . 在 一 些 os 中 ， 它 将 在 dock 中 显示 
win.restore() 
将 最 小 化 的 窗口 恢复 为 之 前 的 状态 . 
win.isMinimized() 

返回 boolean, 窗口 是 否 最 小 化 . 
win.setFullScreen(flag) 

e flag Boolean 
设置 是 否 全 屏 . 

win.isFullScreen() 


返回 boolean, 窗口 是 否 全 屏 化 . 


win.setAspectRatio(aspectRatio[, extrasize]) OSX 


e aspectRatio 维持 部 分 视图 内 容 窗 口 的 高 宽 比 值 . 

e extrasize Object (可 选 ) - 维持 高 宽 比 值 时 不 包含 的 额外 size. 
o width Integer 
© height Integer 


由 一 个 窗口 来 维持 高 宽 比 值 . extrasize 允许 开发 者 使 用 它 ， 它 的 单位 为 像素 ， 不 包含 在 
aspectRatio 中 .这 个 API 可 用 来 区 分 窗口 的 size 和 内 容 的 size . 


想象 一 个 普通 可 控 的 HD video 播放 器 窗口 . 假如 左边 缘 有 15 控 制 像素 ， 右 边缘 有 25 控 制 像 

素 ， 在 播放 器 下 面 有 50 控 制 像素 .为 了 在 播放 器 内 保持 一 个 16:9 的 高 宽 比 例 ， 我 们 可 以 调用 这 
个 api 传 入 参数 16/9 and [ 40, 50 ]. 第 二 个 参数 不 管 网 页 中 的 额外 的 宽度 和 高 度 在 什么 位 置 ， 只 
要 它们 存在 就 行 .只 需要 把 网 页 中 的 所 有 额外 的 高 度 和 宽度 加 起 来 就 行 . 


win.setBounds(options[, animate] ) 


e options Object 
o x Integer 
o y Integer 
o width Integer 
© height Integer 
e animate Boolean (可 选 ) OS X 


重新 设置 窗口 的 宽 高 值 ， 并 且 移 动 到 指定 的 x, y 位 置 . 
win. getBounds( ) 


返回 一 个 对 象 ， 它 包含 了 窗口 的 帘 ， 高 ，X 坐 标 ，y 坐 标 . 


win.setSize(width, height[, animate] ) 


e width Integer 
e height Integer 
e animate Boolean (可 选 ) OS X 


重新 设置 窗口 的 宽 高 值 . 
win. getSize() 


返回 一 个 数组 ， 它 包含 了 窗口 的 宽 ， 


win.setContentSize(width, height[, animate] ) 


e width Integer 
e height Integer 
e animate Boolean (可 选 ) OS X 


重新 设置 窗口 客户 端的 宽 高 值 (例如 网 页 界面 ) . 


win.getContentSize() 


P 


返回 一 个 数组 ， 它 包含 了 窗口 客户 端的 帘 ， 高 . 


win.setMinimumSize(width, height) 


e width Integer 
e height Integer 


设置 窗口 最 小 化 的 宽 高 值 
win.getMinimumSize() 

返回 一 个 数组 ， 它 包含 了 窗口 最 小 化 的 宽 ， 高 . 
win.setMaximumSize(width, height) 


e width Integer 
e height Integer 


设置 窗口 最 大 化 的 宽 高 值 
win.getMaximumSize() 
返回 一 个 数组 ， 它 包含 了 窗口 最 大 化 的 宽 ， 高 . 
win.setResizable(resizable) 

e resizable Boolean 
设置 窗口 是 否 可 以 被 用 户 改变 size. 
win.isResizable() 


返回 boolean, @ 7 Æ T T VIKA P wR ¥size. 


win.setMovable(movable) OS X Windows 


e movable Boolean 


设置 窗口 是 否 可 以 被 用 户 拖 动 . Linux 无 效 . 


win.isMovable() OS X Windows 


返回 boolean ,窗口 是 否 可 以 被 用 户 拖 动 .LinuX 总 是 返回 true. 


win.setMinimizable(minimizable) OS X Windows 


e minimizable Boolean 


设置 窗口 是 否 可 以 最 小 化 . Linux 无 效 . 


win.isMinimizable() OS X Windows 


返回 boolean ,窗口 是 否 可 以 最 小 化 . Linux 总 是 返回 true. 


win.setMaximizable(maximizable) OS X Windows 
e maximizable Boolean 


设置 窗口 是 否 可 以 最 大 化 . Linux 无 效 . 


win.isMaximizable() OS X Windows 


返回 boolean ,窗口 是 否 可 以 最 大 化 .Linux 总 是 返回 true. 


win.setFullScreenable(fullscreenable) 
e fullscreenable Boolean 

设置 点 击 最 大 化 按钮 是 否 可 以 全 屏 或 最 大 化 窗口 
win.isFullScreenable() 


返回 boolean, 点 击 最 大 化 按钮 是 否 可 以 全 屏 或 最 大 化 窗口 . 


win.setClosable(closable) OS X Windows 


e closable Boolean 


设置 窗口 是 否 可 以 人 为 关闭 . Linux HH. 
win.isClosable() OS X Windows 
返回 boolean, 窗 口 是 否 可 以 人 为 关闭 .Linux 总 是 返回 true. 


win. setAlwaysOnTop( flag) 


e flag Boolean 


设置 这 个 窗口 始终 在 其 他 窗口 之 上 .设置 之 后 ， 这 个 窗口 仍然 是 一 个 
个 不 可 以 获得 焦点 的 工具 箱 窗口 . 


win. isAlwaysOnTop() 


返回 boolean, 当 前 窗口 是 否 始终 在 其 它 窗口 之 前 . 
win.center() 

窗口 居中 . 

win.setPosition(x, y[, animate] ) 


e x Integer 
e y Integer 
e animate Boolean (可 选 ) OS X 


移动 窗口 到 对 应 的 x and y 坐标 . 
win. getPosition( ) 
返回 一 个 包含 当前 窗口 位 置 的 数组 
win.setTitle(title) 

e title String 
改变 原 窗 口 的 title. 
win.getTitle() 
返回 原 窗 口 的 title. 
注意 : 界面 title 可 能 和 窗口 title 不 相同 . 
win.flashFrame (flag) 

e flag Boolean 
开始 或 停止 显示 窗口 来 获得 用 户 的 关注 . 
win.setSkipTaskbar (skip) 


e skip Boolean 


普通 的 窗口 ， 不 是 一 


让 窗口 不 在 任务 栏 中 显示 . 


win. setKiosk(flag) 
e flag Boolean 
进入 或 离开 kiosk 模式 . 
win. isKiosk() 


返回 boolean, 是 否 进入 或 离开 kiosk 模式 . 


win.getNativeWindowHandle() 
VA Buffer 形式 返回 这 个 具体 平台 的 窗口 的 幻 柄 . 


windowst 4) #4 XÆ A HwND > OSX nsview* ， Linux window . 


win. hookWindowMessage(message, callback) Windows 


e message Integer 
e callback Function 


拦截 windows 消息 ， 在 WndProc 接收 到 消息 时 触发 callback 函数 . 


win. isWindowMessageHooked(message) Windows 


e message Integer 


返回 true or false 来 代表 是 否 拦截 到 消息 . 


win.unhookwindowMessage(message) Windows 
e message Integer 


不 拦截 窗口 消息 . 


win.unhookAllwindowMessages() Windows 


窗口 消息 全 部 不 拦截. 


win.setRepresentedFilename(filename) OS X 


e filename String 


设置 窗口 当前 文件 路 径 ， 并 且 将 这 个 文件 的 图 标 放 在 窗口 标题 栏 上 


win. getRepresentedFilename() OS X 


获取 窗口 当前 文件 路 径 . 


win.setDocumentEdited(edited) OSX 


e edited Boolean 


明确 指出 窗口 文档 是 否 可 以 编辑 ， 如 果 可 以 编辑 则 将 标题 栏 的 图 标 变 成 灰色 . 


win.isDocumentEdited() OS X 
返回 boolean, 当 前 窗口 文档 是 否 可 编辑 . 

win. focusOnWebView( ) 

win. blurWebView( ) 


win.capturePage([rect, ]callback) 


e rect Object (可 选 ) - 捕获 Page 位 置 
o x Integer 
o y Integer 
o width Integer 
© height Integer 
e callback Function 


捕获 rect PM page 的 快照 .完成 后 将 调用 回调 函数 callback 并 返回 image . image 是 存 
储 了 快照 信息 的 Nativelmage 实 例 .如 果 不 设置 rect 则 将 捕获 所 有 可 见 page. 


win.print([options]) 
类 似 webcontents. print([options]) 


win.printToPDF(options, callback) 


类 似 webContents. printToPDF(options, callback) 


win.loadURL(url[, options] ) 


类 似 webContents.loadURL(url[, options]) . 


win. reload() 


类 似 webcontents.reload . 


win.setMenu(menu) Linux Windows 

e menu Menu 
设置 菜单 栏 的 menu ， 设 置 它 为 null 则 表示 不 设置 菜单 栏 . 
win.setProgressBar (progress) 


e progress Double 
在 进度 条 中 设置 进度 值 ， 有效 范围 [0, 1.0]. 
当 进 度 小 于 0 时 则 不 显示 进度 ; 当 进 度 大 于 0 时 显示 结果 不 确定 . 
在 libux 上 ， 只 支持 Unity 桌 面 环 境 ， 需 要 指明 *.desktop 文件 并 且 在 package.json 中 添加 文 


件 名 字 . 默 认 它 为 app.getName().desktop . 


win.setOverlayIcon(overlay, description) Windows 7+ 


e overlay Nativelmage - 在 底部 任务 栏 右边 显示 图 标 . 
e description String - 描述 . 


向 当前 任务 栏 添 加 一 个 16x16 像素 的 图 标 ， 通 常用 来 覆盖 一 些 应 用 的 状态 ， 或 者 直接 来 提示 
AP. 
win.setHasShadow(hasShadow) OS X 


e hasShadow (Boolean) 


设置 窗口 是 否 应 该 有 阴影 .在 Windows 和 Linux 系 统 无 效 . 


win.hasShadow() OSX 


返回 boolean, 设 置 窗口 是 否 有 阴影 .在 Windows 和 Linux 系 统 始终 返回 true. 


win.setThumbarButtons(buttons) Windows 7+ 


e buttons Array 


在 窗口 的 任务 栏 button 布 局 出 为 缩 略 图 添加 一 个 有 特殊 button 的 缩 略图 工具 栏 . 返回 一 个 
Boolean 对 象 来 指示 是 否 成 功 添 加 这 个 缩 略 图 工具 栏 . 


因为 空间 有 限 ， 缩 略图 工具 栏 上 的 button 数量 不 应 该 超过 7 个 .一 旦 设置 了 ， 由 于 平台 限制 ， 
就 不 能 移动 它 了 .但 是 你 可 使 用 一 个 空 数 组 来 调用 api 来 清除 buttons . 


所 有 buttons 是 一 个 Button 对 象 数 组 : 


e Button Object 
o icon Nativelmage- 在 工具 栏 上 显示 的 图 标 . 
© click Function 
o tooltip String (可 选 )- tooltip 文字 . 
o flags Array (可 选 ) - 控制 button 的 状态 和 行为 . 默认 它 是 ['enabled'] . 


flags 是 一 个 数组 ， 它 包含 下 面 这 些 String S: 


e enabled - button 为 激活 状态 并 且 开 放 给 用 户 . 

e disabled -button 不 可 用 . 目前 它 有 一 个 可 见 的 状态 来 表示 它 不 会 响应 你 的 行为 . 

e dismissonclick - 点 击 button， 这 个 缩 略 窗口 直接 关闭 . 

e nobackground -不 绘制 边框 ， 仅 仅 使 用 图 像 . 

e hidden -button 对 用 户 不 可 见 . 

e noninteractive - button 可 用 但 是 不 可 响应 ; 也 不 显示 按 下 的 状态 . 它 的 值 意味 着 这 是 一 
个 在 通知 单 使 用 button 的 实例 . 

win.showDefinitionForSelection() OSX 


在 界面 查找 选中 文字 时 显示 弹出 字典 ， 


win.setAutoHideMenuBar (hide) 
e hide Boolean 
设置 窗口 的 菜单 栏 是 否 可 以 自动 隐藏 . 一 旦 设置 了 ， 只 有 当 用 户 按 下 Alt 键 时 则 显示 . 
如 果菜 单 栏 已 经 可 见 ， 调 用 setAutoHideMenuBar (true) 则 不 会 立刻 隐藏 . 
win. isMenuBarAutoHide( ) 
返回 boolean, 窗 口 的 菜单 栏 是 否 可 以 自动 隐藏 
win.setMenuBarVisibility(visible) 
e visible Boolean 


设置 菜单 栏 是 否 可 见 . 如 果菜 单 栏 自动 隐藏 ， 用 户 仍然 可 以 按 下 _Alt 键 来 显示 . 


win.isMenuBarVisible() 


返回 boolean, 菜 单 栏 是 否 可 见 . 


win. setVisibleOnAllwWorkspaces(visible) 
e visible Boolean 

设置 窗口 是 否 在 所 有 地 方 都 可 见 . 

注意 : 这 个 api 在 windows 无 效 . 
win.isVisibleOnAllWorkspaces( ) 

返回 boolean, 窗 口 是 否 在 所 有 地 方 都 可 见 . 


注意 : 在 windows 上 始终 返回 false. 


win.setIgnoreMouseEvents(ignore) OSX 


e ignore Boolean 


忽略 窗口 的 所 有 鼠标 事件 . 


contentTracing 


content-tracing 模块 是 用 来 收集 由 底层 的 Chromium content 模块 产 生 的 搜索 数据 . 这 个 模 
块 不 具备 Web 接 口 ， 所 有 需要 我 们 在 chrome 浏 览 器 中 添加 chrome://tracing/ 来 加 载 生 成 文 
件 从 而 查看 结果 . 


const contentTracing = require('electron').contentTracing; 


const options = { 
categoryFilter: 
traceOptions: 'record-until-full, enable-sampling' 


} 


contentTracing.startRecording(options, function() { 
console.log('Tracing started'); 


tii 
了 


setTimeout(function() { 
contentTracing.stopRecording('', function(path) { 
console.log('Tracing data recorded to ' + path); 


content-tracing 模块 的 方法 如 下 : 


contentTracing.getCategories(callback) 


e callback Function 
获得 一 组 分 类 组 . 分 类 组 可 以 更 改 为 新 的 代码 路 径 。 


一 旦 所 有 的 子 进程 都 接受 到 了 getCategories 方法 请 求 ， 分 类 组 将 调用 callback . 


contentTracing.startRecording(options, callback) 


e options Object 
© categoryFilter String 
© traceOptions String 
e callback Function 


开始 向 所 有 进程 进行 记录 .(recording) 


一 旦 收 到 可 以 开始 记录 的 请 求 ， 记 录 将 会 立马 启动 并 且 在 子 进程 是 异步 记录 听 的 . 当 所 有 的 子 
进程 都 收 到 startRecording 请 求 的 时 候 ， callback 将 会 被 调用 . 


categoryFilter 是 一 个 过 滤器 ， 它 用 来 控制 那些 分 类 组 应 该 被 用 来 查找 .过 滤器 应 当 有 一 个 可 
选 的 - 前 组 来 排除 匹配 的 分 类 组 .不 允许 同一 个 列表 既是 包含 又 是 排 斤 . 


例子 : 


© test_MyTest* , 
© test_MyTest*,test_OtherStuff , 


e "-excluded_category1, -excluded_category2 
traceOptions 控制 着 哪 种 查找 应 该 被 启动 ， 这 是 一 个 用 去 号 分 隔 的 列表 .可 用 参数 如 下 : 


© record-until-full 

@ record-continuously 
e trace-to-console 

© enable-sampling 


© enable-systrace 
前 3 个 参数 是 来 查找 记录 模块 4 Ft VG AR EF te RHE traceOptions 中 超过 一 个 跟踪 记录 模 
式 ， 那 最 后 一 个 的 优先 级 最 高 .如 果 没 有 指明 跟踪 记录 模式 ， 那 么 它 默 认为 
record-until-full . 


在 traceoptions 中 的 参数 被 解析 应 用 之 前 ， 查 找 参数 初始 化 默认 为 ( record_mode 设置 为 


record-until-full , enable_sampling 和 enable_systrace 设置 为 ”false ). 


contentTracing.stopRecording(resultFilePath, callback) 


e resultFilePath String 


e callback Function 
停止 对 所 有 子 进程 的 记录 . 


子 进程 通常 缓存 查找 数据 ， 并 且 仅仅 将 数据 截取 和 发 送 给 主 进程 .这 有 利于 在 通过 IPC 发 送 查 
找 数据 之 前 减 小 查找 时 的 运行 开销 ， 这 样 做 很 有 价值 .因此 ， 发 送 查 找 数据 ， 我 们 应 当 蜡 步 通 
知 所 有 子 进 程 来 截取 任何 待 查找 的 数据 . 


a BAA Ft 程 接收 到 了 stopRecording 请 青 求 ， 将 调用 callback > FH AR 个 包含 查找 
数据 的 文件 . 


如 果 resultFilepath 不 为 室 ， 那 么 将 把 查找 数据 写 入 其 中 ， 和 否则 写 入 一 个 临时 文件 .实际 文 
件 路 径 如 果 不 为 室 ， 则 将 调用 callback . 


contentTracing.startMonitoring(options, callback) 


e options Object 
© categoryFilter String 


o traceOptions String 


e callback Function 


开始 向 所 有 进程 进行 监听 .(monitoring) 


一 旦 收 到 可 以 开始 监听 的 请 求 ， 记 录 将 会 立马 启动 并 且 在 子 进程 是 异步 记 监听 的 . 当 所 有 的 子 
程 都 收 到 startMonitoring 请 青 求 的 时 候 ， callback 将 会 被 调用 . 


contentTracing.stopMonitoring(callback) 
e callback Function 


停止 对 所 有 子 进程 的 监听 . 


一 旦 所 有 子 进程 接收 到 了 stopMonitoring 请 青 求 ， 将 调用 callback 


contentTracing.captureMonitoringSnapshot(resultFilePath, cal 
e resultFilePath String 


e callback Function 


获取 当前 监听 的 查找 数据 . 


a 并 且 仅 仅 将 数据 截取 和 发 送 给 主 进程 .因为 如 果 直 接 通过 IPC 来 发 
查找 数据 的 代价 咒 贵 ， 我 们 宁愿 避免 不 必要 的 查找 运行 开销 .因此 ， 为 了 停止 查找 ， 我 们 应 
— 知 所 有 子 进 程 来 截取 任何 待 查找 的 数据 . 


折 有 子 进程 接收 到 了 


一 旦 所 captureMonitoringSnapshot 请 求 ， 将 调用 callback ， 并 且 返 回 
个 包含 查找 数据 的 文件 . 


contentTracing.getTraceBufferUsage(callback) 
e callback Function 


过 查找 buffer 进程 来 获取 百 分 


余 比 最 大 使 用 量 . 当 确定 了 TraceBufferUsage 的 值 确定 的 时 候 ， 
nee 用 callback . 


contentTracing.setWatchEvent(categoryName, eventName, callba 


e categoryName String 


e eventName String 
e callback Function 


任意 时 刻 在 任何 进程 上 指定 事件 发 生 时 将 调用 


callback . 


contentTracing.cancelWatchEvent ( ) 


取消 watch 事件 . 如 果 启 动 查找 ， 这 或 许 会 造成 watch 事件 的 回调 函数 出 错 . 


dialog 


dialog 模块 提供 了 api 来 展示 原生 的 系统 对 话 框 ， 例 如 打开 文件 框 ，alert 框 ， 所 以 Web 应 用 
可 以 给 用 户 带 来 跟 系 统 应 用 相同 的 体验 . 


对 话 框 例 子 ， 展 示 了 选择 文件 和 目录 : 


var win = ...; // BrowserWindow in which to show the dialog 
const dialog = require('electron').dialog; 
console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', 'multiSele 


ee 





OS X 上 的 注意 事项 : 如 果 你 想像 sheets 一 样 展示 对 话 框 ， 只 需要 在 browserWindow BBP 
供 一 个 Browserwindow 的 引用 对 象 . 


方法 
dialog 模块 有 以 下 方法 : 


dialog.showopenDialog([browserwindow，]options[，callback] ) 


e browserwindow BrowserWindow (可 选 ) 
e options Object 
o title String 
o defaultPath String 
o filters Array 
© properties Array - 包含 了 对 话 框 的 特性 值 ， 可 以 包含 openFile , openDirector 
multiSelections and createDirectory 


e callback Function (可 选 ) 


Yy, 


成 功 使 用 这 个 方法 的 话 ， 就 返回 一 个 可 供用 户 选 择 的 文件 路 径 数 组 ， 失 败 返 回 undefined . 


filters 当 需 要 限定 用 户 的 行为 的 时 候 ， 指 定 一 个 文件 数组 给 用 户 展示 或 选择 . 例如 : 


filters: [ 

{ name: 'Images', extensions: ['jpg', 'png', 'gif'] }, 
{ name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] }, 
{ name: 'Custom File Type', extensions: ['as'] }, 

{ name: 'All Files', extensions: ['*'] } 


] 
} 


extensions 数组 应 当 只 包含 扩展 名 ， 不 应 该 包含 通配符 或 '' 号 ( 例 ‘png! 正确 ， 但 是 
',png! 和 '*. png! 不 正确 ). 展示 全 部 文件 的 话 , 使 用 '*， 通配符 SR 配 符 ). 


如 果 callback 被 调用 , 将 异步 调用 API ， 并 且 结 果 将 用 过 callback(filenames) 展示 . 


注意 : 在 Windows 和 Linux ， 一 个 打开 的 dialog 不 能 既是 文件 选择 框 又 是 目录 选择 框 , 所 以 如 
果 在 这 些 平台 上 设置 properties 的 值 为 ['openFile', 'openDirectory'] , 将 展示 一 个 目录 
选择 框 . 


dialog.showSaveDialog([browserWindow, ļoptions[, callback]) 


e browserwindow BrowserWindow (可 选 ) 
e options Object 

o title String 

© defaultPath String 

o filters Array 
e callback Function (可 选 ) 


成 功 使 用 这 个 方法 的 话 ， 就 返回 一 个 可 供用 户 选择 的 文件 路 径 数组 ， 失 败 返 回 undefined . 
filters 指定 展示 一 个 文件 类 型 数组 ， 例子 dialog.showOpenDialog . 


如 果 callback 被 调用 , 将 异步 调用 API ， 并 且 结 果 将 用 过 callback(filenames) 展示 . 


dialog .showMessageBox([browserwindow, ļoptions[, callback]) 


e browserwindow BrowserWindow ("T i) 
e options Object 
o type String - 可 以 是 "none" ， "info" , "error" , "question" 或 "warning" .在 
Windows, "question" 与 "info" 展示 图 标 相 同 , 除非 你 使 用 "icon" BA. 
o buttons Array - buttons 内 容 ， 数 组 . 
o defaultid Integer - 在 message box 对 话 框 打开 的 时 候 ， 设 置 默认 button 选 中 ， 值 
为 在 buttons 数组 中 的 button 索 引 . 
o title String - message box 的 标题 ， 一 些 平台 不 显示 . 
o message String - message box 内 容 . 
o detail String - 额外 信息 . 
o icon Nativelmage 
o cancelld Integer- 当 用 户 关闭 对 话 框 的 时 候 ， 不 是 通过 点 击 对 话 框 的 button， 就 返 
回 值 .默认 值 为 对 应 "cancel" 或 "no" 标签 putton 的 索引 值 , 或 者 如 果 没 有 这 种 
button， 就 返回 0. 在 OSX 和 Windows + > "Cancel" button 的 索引 值 将 一 直 是 
cancelld ,不 管 之 前 是 不 是 特别 指出 的 . 
© noLink Boolean -在 Windows > Electron 将 尝试 识别 哪个 button 是 普通 button (如 
"Cancel" 或 "Yes"), 然后 再 对 话 框 中 以 链接 命令 (command links) 方 式 展 现 其 它 的 


button . 这 能 让 对 话 框 展示 得 很 炫 酷 . 如 果 你 不 喜欢 这 种 效果 ， 你 可 以 设置 noLink 
为 true . 


e callback Function 
展示 message box, 它 会 阻塞 进程 ， 直 到 message box 关闭 为 止 .返回 点 击 按钮 的 索引 值 . 


如 果 callback 被 调用 , 将 异步 调用 API ， 并 且 结 果 将 用 过 callback(response) 展示 . 


dialog.showErrorBox(title, content) 
展示 一 个 传统 的 包含 错误 信息 的 对 话 框 . 


在 app 模块 触发 ready 事件 之 前 ， 这 个 api 可 以 被 安全 调用 ， 通 常 它 被 用 来 在 启动 的 早期 
阶段 报告 错误 . 在 Linux 上 ， 如 果 在 app 模块 触发 ready 事件 之 前 调用 ，message 将 会 被 
触发 显示 stderr， 并 且 没 有 实际 GUI 框 显示 . 


global-shortcut 


global-shortcut 模块 可 以 便捷 的 为 您 设置 (注册 /注销 ) 各 种 自 定 义 操作 的 快捷 键 . 


Note: 使 用 此 模块 注册 的 快捷 键 是 系统 全 局 的 (QQ 截图 那 种 ), 不 要 在 应 用 模块 (app module) 响 
应 ready 消息 前 使 用 此 模块 (注册 快捷 键 ). 


var app = require('app'); 
var globalShortcut = require('global-shortcut'); 


app.on('ready', function() { 
// Register a 'ctrl+x' shortcut listener. 
var ret = globalShortcut.register('ctrl+x', function() { 
console.log('ctrl+x is pressed'); 


}) 
if (!ret) { 
console.log('registration failed'); 

} 

// Check whether a shortcut is registered. 

console.log(globalShortcut.isRegistered('ctrl+x')); 
H); 
app.on('will-quit', function() { 

// Unregister a shortcut. 

globalShortcut.unregister('ctrl+x'); 

// Unregister all shortcuts. 


globalShortcut.unregisterAll(); 
}); 


Methods 
global-shortcut 模块 包含 以 下 元 数 : 


globalShortcut.register(accelerator, callback) 


e accelerator Accelerator 
e callback Function 


注册 accelerator 快捷 键 . 当 用 户 按 下 注册 的 快捷 键 时 将 会 调用 callback Max. 


globalShortcut .isRegistered(accelerator ) 


e accelerator Accelerator 


查询 accelerator 快捷 键 是 否 已 经 被 注册 过 了 ,将 会 返回 true (已 被 注册 ) 或 false (未 注 


globalShortcut .unregister (accelerator) 
è accelerator Accelerator 
注销 全 局 快捷 键 accelerator . 

globalShortcut .unregisterAll() 


注销 本 应 用 注册 的 所 有 全 局 快捷 键 . 


ipcMain 


ipcMain 模块 是 类 EventEmitter 的 实例 . 当 在 主 进 chek 它 的 时 候 ， 它 控制 着 由 泻 染 进程 
(web mA 来 的 异步 或 同步 消息 .从 泻 染 进程 发 送 过 来 的 消息 将 触发 事件 . 


发 送 消息 
同样 也 可 以 从 主 进 程 向 泻 染 进 程 发 送 消息 ， 查 看 更 多 webContents.send . 


° 发 送 消 息 ies channel . 
e 回应 同步 消息 ， 你 可 以 设置 event.returnvalue . 
e 回应 异步 消息 息 , 你 可 以 使 用 event.sender.send(...). 


一 个 例子 ， 在 主 进程 和 演 染 进程 之 间 发 送 和 处 理 消 息 : 


// In main process. 
const ipcMain = require('electron').ipcMain; 
ipcMain.on('asynchronous-message', function(event, arg) { 
console.log(arg); // prints "ping" 
event.sender.send( 'asynchronous-reply', 'pong'); 
H); 
ipcMain.on('synchronous-message', function(event, arg) { 
console.log(arg); // prints "ping" 
event.returnValue = 'pong'; 


}); 


// In renderer process (web page). 
const ipcRenderer = require('electron').ipcRenderer; 
console.log(ipcRenderer.sendSync('synchronous-message', 'ping')); // prints "pong" 
ipcRenderer.on('asynchronous-reply', function(event, arg) { 

console.log(arg); // prints "pong" 


}); 


ipcRenderer.send('asynchronous-message', 'ping'); 


监听 消息 
ipcMain 模块 有 如 下 监听 事件 方法 : 


ipcMain.on(channel, listener ) 


e channel String 
e listener Function 


监听 channel , 当 新 消息 到 达 ， 将 通过 listener(event, args...) 调用 listener . 


ipcMain.once(channel, listener) 


e channel String 
e listener Function 


为 事件 添加 一 个 一 次 性 用 的 listener 部 数 .这 个 listener 只 有 在 下 次 的 消息 到 达 channel 
时 被 请 求 调用 ， 之 后 就 被 删除 了 . 


ipcMain.removeListener(channel, listener) 


e channel String 
e listener Function 


为 特定 的 channel 从 监听 队列 中 删除 特定 的 listener 监听 者 . 


ipcMain.removeAllListeners([channel] ) 


e channel String (7 %) 


删除 所 有 监听 者 ， 或 特 指 的 channel 的 所 有 监听 者 . 
TET: 
传递 给 callback 的 event 对 象 有 如 下 方法 : 


event .returnValLue 


将 此 设置 为 在 一 个 同步 消息 中 返回 的 值 


event. sender 


Pas 
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返回 发 送 消息 的 webContents ， 你 可 以 调用 event.sender.send 来 回复 异步 消息 


webContents.send. 


+ 
EA 


IN 


单 


menu 类 可 以 用 来 创建 原生 菜 六 


€ 


可 用 作 应 用 菜单 和 context 菜单 . 


这 个 模块 是 一 个 主 进程 的 模块 ， 并 且 可 以 通过 remote Mike RUA A. 


每 个 菜单 有 一 个 或 几 个 菜单 项 Menu 


items ， 并 且 每 个 菜单 项 可 以 有 子 菜 六 


下 面 这 个 例子 是 在 网 页 ( 泻 染 进 程 ) 中 通过 remote 模块 动态 创建 的 菜单 ， 并 且 右 键 显示 : 


<!-- index.html --> 
<SC hi pit= 

const remote = 
const Menu remote .Menu; 

const MenuItem remote .MenuItem; 


var menu new Menu(); 

menu.append(new MenuItem({ label: 
menu.append(new MenulItem({ type: 
menu.append(new MenuItem({ label: 


require('electron').remote; 


"MenuItem1', click: function() { console.log('item 1 cl 
"separator' })); 


"MenuItem2', type: 'checkbox', checked: true })); 


window.addEventListener('contextmenu', function (e) { 
e.preventDefault(); 
menu.popup(remote.getCurrentWindow()); 

b false); 

</script> 





BF > SUA P AA apit E oe ARS: 


var template = [ 
{ 
label: Editi 
submenu: [ 

label: 'Undo', 
accelerator: 'CmdOrCtrl+z', 
role: 'undo' 

}, 

{ 
label: 'Redo', 
accelerator: '‘Shift+CmdOrCtrl1+z', 
role: 'redo' 

}, 

{ 
type: 'separator' 

}, 

{ 
label: 'Cut', 
accelerator: 'CmdOrCtr1+x', 
role: 'cut' 

}, 

{ 
label: 'Copy', 
accelerator: 'CmdOrCtr1+C', 
role: 'copy' 

}, 

{ 
label: 'Paste', 
accelerator: 'CmdOrCtrl+v', 


role: 'paste' 


}, 
{ 
label: ‘Select All', 
accelerator: 'CmdOrCtr1+A', 
role: 'selectall' 
}, 
] 
}, 
{ 


label: 'View', 
submenu: [ 


label: 'Reload', 
accelerator: 'CmdOrCtri1+R', 
click: function(item, focusedWindow) { 
if (focusedWindow) 
focusedWindow. reload(); 
} 


}, 
{ 
label: 'Toggle Full Screen', 
accelerator: (function() { 
if (process.platform == 'darwin') 
return 'Ctrl+Command+F'; 
else 
return 'F11'; 
HO, 
click: function(item, focusedwWindow) { 


if (focusedWindow) 
focusedWindow. setFullScreen( ! focusedWindow.isFullScreen()); 
} 


}, 
{ 
label: 'Toggle Developer Tools', 
accelerator: (function() { 
if (process.platform == 'darwin') 
return 'Alt+Command+I'; 
else 
return "Ctrl Shahire 
HO, 
click: function(item, focusedWindow) { 


if (focusedWindow) 
focusedWindow. toggleDevTools(); 


}, 


label: 'Window', 
role: 'window', 
submenu: [ 


label: 'Minimize', 
accelerator: 'CmdOrCtrl+M', 
role: 'minimize' 


}, 

{ 
label: 'Close', 
accelerator: 'CmdOrCtrl+w', 
role: 'close' 

}, 


] 
}, 
{ 
label: 'Help', 


role: 'help', 
submenu: [ 


label: ‘Learn More', 
click: function() { require('electron').shell.openExternal('http://electron.atom. 


}, 


] 
i 
J; 


if (process.platform == 'darwin') { 
var name = require('electron').remote.app.getName(); 
template.unshift({ 
label: name, 
submenu: [ 
{ 
label: 'About ' + name, 
role: 'about' 


type: 'separator' 


label: 'Services', 
role: "services', 
submenu: [] 


type: 'separator' 


label: ‘Hide ' + name, 
accelerator: 'Command+H', 
role: 'hide' 


label: ‘Hide Others', 
accelerator: 'Command+Alt+H', 
role: 'hideothers' 


label: 'Show All', 
role: 'unhide' 


} 
{ 
type: 'separator' 
} 
{ 


label: 'Quit', 
accelerator: 'Command+Q', 
click: function() { app.quit(); } 
} 
] 
}); 


// Window menu. 
template[3].submenu.push( 


type: 'separator' 
}, 


{ 
label: 'Bring All to Front', 


role: 'front' 
} 
); 
} 


var menu = Menu.buildFromTemplate(template); 
Menu. setApplicationMenu(menu); 


He== = === 





类 : Menu 


new Menu() 


AN — A HY HK 
方法 
菜单 类 有 如 下 方法 : 


Menu.setApplicationMenu (menu) 


e menu Menu 


在 OS X 上 设置 应 用 菜单 menu . 


menu . 


在 windows 和 linux， 是 为 每 个 窗口 都 在 其 顶部 设置 菜单 


Menu.sendActionToFirstResponder(action) OSX 


e action String 


发 送 action 给 应 用 的 第 一 个 响应 器 .这 个 用 来 模仿 Cocoa 菜单 的 默认 行为 ， 通 常 你 只 需要 使 
用 MenuItem 的 属性 role . 


查看 更 多 OS X 的 原生 action OS X Cocoa Event Handling Guide . 


Menu . buildFromTemplate(template) 
e template Array 
一 般 来 说 ， template 只 是 用 来 创建 Menultem 的 数组 参数 . 


你 也 可 以 向 template 元 素 添 加 其 它 东 西 id 并 且 他 们 会 变 成 已 经 有 的 菜单 项 的 属性 
实例 方法 
menu 对 和 象 有 如 下 实例 方法 


menu.popup([browserWindow, x, y, positioningItem] ) 


e browserwindow BrowserWindow (可 选 ) - 默认 为 null. 
e x Number (可 选 ) - 默认 为 -1. 
e y Number (必须 如 果 X 设 置 了 ) - 默认 为 -1. 


e positioningItem Number (可 选 ) OS X- 在 指定 坐标 鼠标 位 置 下 面 的 菜单 项 的 索引 . 默认 
为 -1. 


在 browserWindow 中 弹出 context menu .你 可 以 选择 性 地 提供 指定 的 x， y 来 设置 菜单 应 该 
放 在 哪里 ,否则 它 将 默认 地 放 在 当前 鼠标 的 位 置 


menu . append ( menuItem) 
e menuItem Menultem 
添加 菜单 项 . 
menu.insert(pos, menuItem) 


e pos Integer 


e menuItem Menultem 
在 制定 位 置 添加 菜单 项 . 
menu.items() 


获取 一 个 菜单 项 数组 . 


OS X Application 上 的 菜单 的 注意 事项 


相对 于 windows 和 linux, OS X 上 的 应 用 菜单 是 完全 不 同 的 style， 这 里 是 一 些 注意 事项 ， 来 让 
你 的 菜单 项 更 原生 化 . 


在 OSX 上 ， 有 很 多 系统 定义 的 标准 菜单 ， 例 如 services and windows 菜单 .为 了 让 你 的 应 
用 更 标准 化 ， 你 可 以 为 你 的 菜单 的 role 设置 值 ， 然 后 electron 将 会 识别 他 们 并 且 让 你 的 菜 
单 更 标准 : 


© window 
© help 


© services 


标准 菜单 项 行为 


OS X 为 一 些 菜单 项 提供 了 标准 的 行为 方法 ， 例 如 About xxx , Hide xxx , aNd Hide Others . 
为 了 让 你 的 菜单 项 的 行为 更 标准 化 ， 你 应 该 为 菜单 项 设置 role 属性 . 


主 菜单 名 


在 OS X， 无 论 你 设置 的 什么 标签 ， 应 用 菜单 的 第 一 个 菜单 项 的 标签 始终 未 你 的 应 用 名 字 . 想 
要 改变 它 的 话 ， 你 必须 通过 修改 应 ae Info.plist 文件 来 修改 应 用 名 字 . 更 多 信息 参 
考 About Information Property List Files . 


为 制定 浏览 器 窗口 设置 菜单 (Linux Windows) 


也 


浏览 器 窗口 的 [ setMenu 方法 ][setMenu] 能 够 设置 菜单 为 特定 浏览 器 窗口 的 类 


当 通 过 Menu. buildFromTemplate 4 菜单 的 时 候 ， ， 你 可 以 使 用 position and id 来 放置 
单项 . 


MenuItem 的 属性 position 格式 为 [placement]=[id] ? placement 取 值 为 before , 
after ,或 endof 和 id ， id 是 菜单 已 经 存在 的 菜单 项 的 唯一 1D: 


© before -在 对 应 引用 id 菜单 项 之 前 插入 . 如 果 引 用 的 菜单 项 不 存在 ， 则 将 其 插 在 菜单 末 
尾 . 

e after -在 对 应 引用 id 菜单 项 之 后 插入 . 如 果 引 用 的 菜单 项 不 存在 ， 则 将 其 插 在 菜单 末尾 . 

。 endof -在 逻辑 上 包 ee omental ne 单项 不 存在 , 则 将 
使 用 给 定 的 id 创 建 一 个 新 的 集合 ， 并 且 这 个 菜单 项 将 插入 . 


当 一 个 菜 档 项 插入 成 功 了 ， Oe E a 
想 在 同一 个 位 置 插入 一 组 菜单 项 ， 只 需要 为 这 组 菜单 项 的 第 一 个 指定 位 置 . 


| F 


模板 : 


{label: '4', id: '4'}, 
{label: "5", id: SO 
{label: '1', id: '1', position: 'before=4'}, 
falta beh: 2A 0 ents, 
{label: '3', id: '3'} 


y% 
B 


RM wt mw o 
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模板 : 


{label: 
{label: 
{label: 
{label: 
{label: 
{label: 


1 
WONF!OAT®D ! 


[setMenu]: https://github.com/electron/electron/blob/master/docs/api/browser- 
window.md#winsetmenumenu-linux-windows 


Menu 


position: 
position: 
position: 
position: 
position: 
position: 


‘endof=letters'}, 
‘endof=numbers'}, 
‘endof=letters'}, 
‘endof=numbers'}, 
‘endof=letters'}, 
‘endof=numbers '} 
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菜单 项 


菜单 项 模块 允许 你 向 应 用 或 menu 添 加 选项 。 


查看 menu 例 子 。 
类 : Menultem 
使 用 下 面 的 方法 创建 一 个 新 ÁJ MenuItem 


new Menultem(options) 


e options Object 
o click Function - 当 菜 单项 被 点 击 的 时 候 ， 使 用 click(menuItem,browserwindow) 调 
用 


o role String- 定义 菜单 项 的 行为 ， 在 指定 click 属性 时 将 会 被 忽略 
o type String - 取 值 normal °’ separator ， checkbox Or radio 


o label String 

© sublabel String 

© accelerator Accelerator 

o icon Nativelmage 

o enabled Boolean 

o visible Boolean 

o checked Boolean 

© submenu Menu - 应 当 作 为 submenu 菜单 项 的 特定 类 型 ， 当 它 作为 

type: 'submenu' 菜单 项 的 特定 类 型 时 可 以 忽略 。 如 果 它 的 值 不 是 Menu ， 将 自动 转 
为 Menu.buildFromTemplate ° 

id String - 标志 一 个 菜单 的 唯一 性 。 如 果 被 定义 使 用 ， 它 将 被 用 作 这 个 菜单 项 的 参 
考 位 置 属性 。 

© position String - 定义 给 定 的 菜单 的 具体 指定 位 置信 息 。 


oO 


在 创建 菜单 项 时 ， 如 果 有 匹配 的 方法 ， 建 议 指定 role 属性 ， 不 需要 人 为 操作 它 的 行为 ， 这 
样 菜单 使 用 可 以 给 用 户 最 好 的 体验 。 


role 属性 值 可 以 为 : 


© undo 
© redo 
@ cut 


@ paste 

èe Selectal1 

® minimize - 最 小 化 当前 窗口 
e close -关闭 当前 窗口 


在 OSX 上 ，role 还 可 以 有 以 下 值 : 


e about - 匹配 orderFrontStandardAboutPanel 行为 
e hide -匹配 hide 行为 

e hideothers - 匹配 hideOtherApplications 行为 
e unhide - 匹配 unhideAllApplications 行为 

e front -匹配 arrangeInFront 行为 

e window - "Window" 菜单 项 

e help - "Help" 菜单 项 

e services - "Services" 菜单 项 


powerMonitor 


power -monitor 模块 是 用 来 监听 能 源 区 改变 的 .只 能 在 主 进 程 中 使 用 .在 app 模块 的 ready 事 
件 触 发 之 后 就 不 能 使 用 这 个 模块 了 . 


例如 : 


app.on('ready', function() { 
require('electron').powerMonitor.on('suspend', function() { 

console.log('The system is going to sleep'); 

}); 

}); 


事件 


power-monitor 模块 可 以 触发 下 列 事件 : 


Event: suspend 


在 系统 挂 起 的 时 候 触发 . 


Event: ‘resume’ 


在 系统 恢复 继续 工作 的 时 候 触发 . Emitted when system is resuming. 


Event: ‘on-ac' 


在 系统 使 用 交流 电 的 时 候 触 发 . Emitted when the system changes to AC power. 


Event: 'on-battery' 


在 系统 使 用 电池 电源 的 时 候 触发 . Emitted when system changes to battery power. 


powerSaveBlocker 

powerSaveBlocker 模块 是 用 来 阻止 应 用 系统 进入 睡 眠 模式 的 2 此 这 允许 应 用 保持 A FH Aa He 
幕 继续 工作 . 

例如 : 


const powerSaveBlocker = require('electron').powerSaveBlocker; 


var id = powerSaveBlocker.start('prevent-display-sleep'); 
console.log(powerSaveBlocker.isStarted(id)); 


powerSaveBlocker.stop(id); 


万 法 
powerSaveBlocker 模块 有 如 下 方法 : 


powerSaveBlocker.start(type) 


e type String - 强行 保存 阻塞 类 型 
© prevent-app-suspension - 阻止 应 用 挂 起 . 保持 系统 活跃 ， 但 是 允许 屏幕 不 亮 . 用 例 : 
下 载 文件 或 者 播放 音频 . 
© prevent-display-sleep - 阻止 应 用 进入 休 眼 . 保持 系统 和 屏幕 活跃 ， 屏 幕 一 直 亮 . 用 
Bl: 播放 音频 . 


开始 阻止 系统 进入 睡眠 模式 .返回 一 个 整数 ， 这 个 整数 标识 了 保持 活跃 的 blocker. 


注意 : prevent-display-sleep 有 更 高 的 优先 级 prevent-app-suspension . 只 有 最 高 优先 级 生 
BK. 换 名 话说 ， prevent-display-sleep 优先 级 永远 高 于 prevent-app-suspension . 


例如 ， 人 请 求 调用 了 prevent-app-suspension , B 请 求 调 用 了 prevent-display-sleep . 
prevent-display-sleep 将 一 直 工 作 直到 B 停 止 调 用 . 在 那 之 后 ， prevent-app-suspension 才 
起 效 . 


powerSaveBlocker .stop(id) 
e id Integer -通过 powerSaveBlocker.start 返回 的 保持 活跃 的 blocker id. 


让 指定 blocker 停止 活跃 . 


powerSaveBlocker.isStarted(id) 


e id Integer -通过 powerSaveBlocker.start 返回 的 保持 活跃 的 blocker id. 


返回 boolean ， 是 否 对 应 的 powerSaveBlocker 已 经 启动 . 


协议 


protocol 模块 可 以 注册 一 个 自 定义 协议 ， 或 者 使 用 一 个 已 经 存在 的 协议 . 
例子 ， 使 用 一 个 与 file:// 功能 相似 的 协议 : 


const electron = require('electron'); 
const app = electron.app; 
const path = require('path'); 


app.on('ready', function() { 
var protocol = electron.protocol; 


protocol.registerFileProtocol('atom', function(request, callback) { 
var url = request.url.substr(7); 


callback({path: path.normalize(__dirname + '/' + url)}); 
i, tunction (error) re 


if (error) 
console.error('Failed to register protocol') 
3); 


3); 


注意 : 这 个 模块 只 有 在 app 模块 的 ready 事件 触发 之 后 才 可 使 用 . 
方法 
protocol 模块 有 如 下 方法 : 


protocol.registerStandardSchemes (schemes) 


schemes Array - 将 一 个 自 定义 的 方案 注册 为 标准 的 方案 . 


一 个 标准 的 scheme 遵循 RFC 3986 的 generic URI syntax 标准 . 这 包含 了 file: 和 
filesystem: . 


protocol. registerServiceWorkerSchemes (schemes) 


e schemes Array - 将 一 个 自 定义 的 方案 注册 为 处 理 service workers. 


protocol.registerFileProtocol(scheme, handler[, completion] ) 


e scheme String 


e handler Function 


e completion Function (可 选 ) 


注册 一 个 协议 ， 用 来 发 送 响应 文件 . 当 通过 这 个 协议 来 发 起 一 个 请 求 的 时 候 ， 将 使 用 
handler(request, callback) 来 调用 handler . 当 scheme 被 成 功 注册 或 者 完成 ( BIR) AT A 
败 ， 将 使 用 completion(null) 调用 completion . 


e request Object 

o url String 

o referrer String 

© method String 

o uploadData Array (可 选 ) 
e callback Function 


uploadData 是 一 个 data 对 象 数 组 : 


e data Object 
o bytes Buffer - 被 发 送 的 内 容 . 
o file String- 上 传 的 文件 路 径 . 


为 了 处 理 请 求 ， 调 用 callback 时 需要 使 用 文件 路 径 或 者 一 个 带 path 参数 的 对 象 ,例如 
callback(filePath) 或 callback({path: filePath}) . 


当 不 使 用 任何 参数 调用 callback 时 ， 你 可 以 指定 一 个 数字 或 一 个 带 有 error 参数 的 对 象 ， 
来 标识 request 失败 .你 可 以 使 用 的 error number 可 以 参考 net error list. 


默认 scheme 会 被 注册 为 一 个 http: 协议 ， 它 与 遵循 "generic URI syntax" 规则 的 协议 解析 
不 同 ， 例 如 file: ， 所 以 你 或 许 应 该 调用 protocol.registerStandardSchemes 来 创建 一 个 标 
准 的 scheme. 


protocol.registerBufferProtocol(scheme, handler[, completion 


e scheme String 
e handler Function 
e completion Function (可 选 ) 


注册 一 个 scheme 协议， 用 来 发 送 响应 Buffer 


这 个 方法 的 用 法 类 似 registerFileProtocol ， 除非 使 用 一 个 Buffer Xt ? 或 一 个 有 data , 
mimeType , 和 charset 属性 的 对 象 来 调用 callback . 


例子 : 


protocol.registerBufferProtocol('atom', function(request, callback) { 
callback({mimeType: 'text/html', data: new Buffer('<h5>Response</h5>' )}); 
y, function (error) £ 
if (error) 
console.error('Failed to register protocol') 


3); 


protocol.registerStringProtocol(scheme, handler[, completion 


e scheme String 
e handler Function 
e completion Function (可 选 ) 


注册 一 个 scheme 协议 ， 用 来 发 送 响应 string . 


这 个 方法 的 用 法 类 似 registerFileProtocol ° 除非 使 用 一 个 String XY g 或 一 个 有 data , 
mimeType , 和 charset 属性 的 对 象 来 调用 callback . 


protocol.registerHttpProtocol(scheme, handler[, completion] ) 


e scheme String 
e handler Function 


e completion Function (可 选 ) 
注册 一 个 scheme 协议 ， 用 来 发 送 HTTP 请 求 作 为 响应 . 
这 个 方法 的 用 法 类 似 registerFileProtocol ， 除非 使 用 一 个 redirectRequest XY ， 或 一 个 
有 url , method , referrer , uploadData 和 session 属性 的 对 象 来 调用 callback . 


e redirectRequest Object 
o url String 
© method String 
o session Object (可 选 ) 
o uploadData Object (可 选 ) 


默认 这 个 HTTP 请 求 会 使 用 当前 session .如 果 你 想 使 用 不 同 的 session 值 ， 你 应 该 设置 


session 为 null . 
POST 请 求 应 当 包 含 uploaddata IŽ. 


e uploadData object 


o contentType String - A 4) MIME type. 
o data String - 被 发 送 的 内 容 . 
protocol.unregisterProtocol(scheme[, completion] ) 


e scheme String 


e completion Function (可 选 ) 


注销 自 定 义 协 议 scheme . 


protocol.isProtocolHandled(scheme, callback) 


e scheme String 
e callback Function 


将 使 用 一 个 布尔 值 来 调用 callback ， 这 个 布尔 值 标 识 了 是 否 已 经 存在 scheme 的 句柄 了 . 


protocol.interceptFileProtocol(scheme, handler[, completion] 


e scheme String 
e handler Function 
e completion Function (可 选 ) 


拦截 scheme 协议 并 且 使 用 handler 作为 协议 的 新 的 句柄 来 发 送 响应 文件 . 


protocol.interceptStringProtocol(scheme, handler[, completio 


e scheme String 
e handler Function 
e completion Function ("T 3%) 


拦截 scheme 协议 并 且 使 用 handler 作为 协议 的 新 的 句柄 来 发 送 响 应 string . 


protocol.interceptBufferProtocol(scheme, handler[, completio 


e scheme String 
e handler Function 
e completion Function (可 选 ) 


拦截 scheme 协议 并 且 使 用 handler 作为 协议 的 新 的 句柄 来 发 送 响 应 Buffer . 


protocol.interceptHttpProtocol(scheme, handler[, completion] 


e scheme String 
e handler Function 
e completion Function (optional) 


拦截 scheme 协议 并 且 使 用 handler 作为 协议 的 新 的 句柄 来 发 送 新 的 响应 HTTP 请 求 . 
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a 
new HTTP request as a response. 


protocol.uninterceptProtocol(scheme[, completion] ) 


e scheme String 
e completion Function 取消 对 scheme 的 拦截 ， 使 用 它 的 原始 句柄 进行 处 理 . 


session 


session 模块 可 以 用 来 创建 一 个 新 的 session 对 象 . 


你 也 可 以 通过 使 用 webContents 的 属性 session 来 使 用 一 个 已 有 页 面 的 session 


” webContents 是 BrowserWindow 的 属性 . 


const BrowserWindow = require('electron').BrowserWindow; 


var win = new BrowserWindow({ width: 800, height: 600 }); 
win. loadURL("http://github.com"); 


var ses = win.webContents.session; 


万 法 

session 模块 有 如 下 方法 : 

session.fromPartition(partition) 
e partition String 


从 字符 串 partition 返回 一 个 新 的 session 实例 . 


如 果 partition 以 persist: 开头 ， 那 么 这 个 page 将 使 用 一 个 持久 的 session， 这 个 
session 将 对 应 用 的 所 有 page 可 用 .如 果 没 前 缓 ， 这 个 page 将 使 用 一 个 历史 session. 如 果 
partition 为 室 ， 那 么 将 返回 应 用 的 默认 session . 


属性 
session ZA ho FOB, TE: 
session.defaultSession 


返回 应 用 的 默认 session 对 象 . 


Class: Session 


可 以 在 session 模块 中 创建 一 个 session 对象 : 


const session = require('electron').session; 


var ses = session.fromPartition('persist:name'); 


实例 事件 
实例 session 有 以 下 事件 : 


Event: 'will-download' 


e event Event 
e item Downloadltem 
è webContents \VVebContents 


当 Electron 将 要 从 webcontents 下 载 item 时 触发 . 


调用 event.preventDefault() 可 以 取消 下 载 ， 并 且 在 进程 的 下 个 tick 中 ， 这 个 item 也 不 可 
用 . 


session.defaultSession.on('will-download', function(event, item, webContents) { 
event.preventDefault(); 
require('request')(item.getURL(), function(data) { 
require('fs').writeFileSync('/somewhere', data); 
3); 
3); 


实例 方法 
实例 session 有 以 下 方法 : 


ses.cookies 


cookies 赋予 你 全 力 来 查询 和 修改 cookies. 例如 : 


// 查询 所 有 cookies. 
session.defaultSession.cookies.get({}, function(error, cookies) { 
console.log(cookies); 


3); 


// 查询 与 指定 url 相关 的 所 有 cookies. 
session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, coo 
console.log(cookies); 


3); 


// 设置 cookie; 
// may overwrite equivalent cookies if they exist. 


var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" }; 
session.defaultSession.cookies.set(cookie, function(error) { 
if (error) 


console.error(error); 


}); 











ses.cookies.get(filter, callback) 


e filter Object 
o url String (可 选 ) - 与 获取 cookies 相关 的 url .不 设置 的 话 就 是 从 所 有 url 获取 
cookies . 


Lo 


name String (* 2) - 通过 name 过 滤 cookies. 

o domain String (可 选 ) - 获取 对 应 域名 或 子 域名 的 cookies . 

o path String (可 选 ) - 获取 对 应 路 径 的 Cookies . 

o secure Boolean (可 选 ) - 通过 安全 性 过 滤 cookies. 

o session Boolean (可 选 ) - 过 滤 掉 session 或 持久 的 cookies. 


e callback Function 


发 送 一 个 请 求 ， 和 希望 获得 所 有 匹配 details 的 cookies, 在 完成 的 时 候 ， 将 通过 
callback(error, cookies) 调用 callback . 


cookies 是 一 个 cookie  &. 


e cookie Object 

o name String - cookie 2. 

o value String - cookie 值 . 

o domain String - cookie 域 名 . 

o hostonly String - 是 否 cookie 是 一 个 host-only cookie. 

o path String - cookie 路 径 . 

o secure Boolean - 是 否 是 安全 cookie. 

o httponly Boolean - 是 否 只 是 HTTP cookie. 

© session Boolean - cookie 是 否 是 一 个 session cookie 或 一 个 带 截至 日 期 的 持久 
cookie . 

o expirationDate Double (可 选 ) - cookie 的 截至 日 期 ， 数 值 为 UNIX 纪 元 以 来 的 秒 数 . 
对 session cookies 不 提供 . 


ses.cookies.set(details, callback) 


e details Object 
o url String -与 获取 cookies 相关 的 url. 
o name String - cookie 名 . 忽略 默认 为 空 . 
o value String - cookie 值 . 忽略 默认 为 空 . 
o domain String - cookie 的 域名 . 忽略 默认 为 空 . 
o path String - cookie 的 路 径 . 忽略 默认 为 空 . 
© secure Boolean - 是 否 已 经 进行 了 安全 性 标识 . 默认 为 false. 
o session Boolean - 是 否 已 经 HttpOnly 标识 . 默认 为 false. 
© expirationDate Double - cookie 的 截至 日 期 ， 数 值 为 UNIX 纪 元 以 来 的 秒 数 . ORB 
略 , cookie 变 为 session cookie. 
e callback Function 


使 用 details 设置 cookie, 完成 时 使 用 callback(error) 掉 哟 个 callback . 


ses.cookies.remove(url, name, callback) 


e url String - 4 cookies 相关 的 url. 
e name String - 需要 删除 的 cookie 4. 


e callback Function 
删除 匹配 url 和 name 的 cookie, 完成 时 使 用 callback() 调用 callback . 
ses.getCacheSize(callback) 


e callback Function 
o size Integer- 单位 bytes 的 缓存 size. 


返回 session 的 当前 缓存 size . 
ses.clearCache(callback) 
e callback Function - 操作 完成 时 调用 
清空 session 的 HTTP %& 7. 
ses.clearStorageData([options, ]callback) 
e options Object (可 选 ) 


origin String - & 4 3848 window. location.origin 的 格式 scheme://host:port . 
storages Array - 需要 清理 的 storages 类 型 , 可 以 包含 : appcache , cookies , 


o 


o 


filesystem , indexdb , local storage , shadercache , websql , serviceworkers 


quotas Array - 需要 清理 的 类 型 指标 ， 可 以 包含 : temporary , persistent , 


syncable . 
e callback Function - 操作 完成 时 调用 . 


清除 web storages 的 数据 . 
ses.flushStorageData() 

将 没有 写 入 的 DOMStorage 写 入 磁盘 . 
ses.setProxy(config, callback) 


e config Object 
o pacScript String -与 PAC 文件 相关 的 URL. 


o proxyRules String - 代理 使 用 规则 . 
e callback Function - 操作 完成 时 调用 . 


设置 proxy settings. 


4 pacScript 和 proxyRules 一 同 提供 时 ， 将 忽略 proxyRules ， 并 且 使 用 pacScript 配置 


proxyRules 需要 遵循 下 面 的 规则 : 


proxyRules = schemeProxies[";'"<schemeProxies>] 
schemeProxies = [<urlScheme>"="]<proxyURIList> 

urlScheme = "http" | "https" | "ftp" | "socks" 
proxyURIList = <proxyURL>[","<proxyURIList>] 

proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>] 


例子 : 


e http=foopy:80;ftp=foopy2 -为 http:// URL 使 用 HTTP 代理 foopy:s0 ,和 为 
ftp:// URL HTTP 代理 foopy2:80 . 

e foopy:s0 - APTA URL 1%] HTTP 代理 foopy:86 . 

© foopy:80,bar,direct:// -为 所 有 URL 使 用 HTTP 代理 foopy:30 ,如 果 foopy:so 不 
可 用 ， 则 切换 使 用 bar , 再 往 后 就 不 使 用 代理 了 . 

© socks4://foopy -为 所 有 URL 使 用 SOCKS v4 代理 foopy:1080 . 

© http=foopy,socks5://bar.com -为 所 有 URL 使 用 HTTP 代理 foopy , 如果 foopy 不 可 
用 ， 则 切换 到 SOCKS5 代理 bar.com . 

© http=foopy,direct:// -为 所 有 http url 使 用 HTTP 代理 ， 如 果 foopy 不 可 用 ， 则 不 使 用 
代理 . 

e http=foopy;socks=foopy2 -为 所 有 http url 使 用 foopy 代理 ， 为 所 有 其 他 Url 使 用 
socks4://foopy2 代理 . 


ses.resolveProxy(url, callback) 


e url URL 
e callback Function 


解析 url 的 代理 信 $, 当 请 求 完 成 的 时 候 使 用 callback(proxy) 调用 callback . 
ses.setDownloadPath( path) 
e path String - 下 载 地 址 


设置 下 载 保存 地 址 ， 软 认 保 存 地 址 为 各 自 app 应 用 的 Downloads 目录 . 
ses.enableNetworkEmulation(options) 


e options Object 
o offline Boolean - 是 否 模拟 网 络 故障 . 
o latency Double - 每 毫秒 的 RTT 
© downloadThroughput Double - 每 Bps 的 下 载 速率 . 
© uploadThroughput Double - 每 Bps 的 上 载 速 率 . 


通过 给 定 配 置 的 session 来 模拟 网 络 . 


// 模拟 GPRS 连接 ， 使 用 的 50kbps 流量 ，500 毫秒 的 rtt. 
window.webContents.session.enableNetworkEmulation({ 
latency: 500, 
downloadThroughput: 6400, 
uploadThroughput: 6400 


3); 


// 模拟 网 络 故障 , 
window.webContents.session.enableNetworkEmulation({offline: true}); 


ses.disableNetworkEmulation() 


停止 所 有 已 经 使 用 session 的 活跃 模拟 网 络 . 重 置 为 原始 网 络 类 型 . 


ses.setCertificateVerifyProc(proc) 
e proc Function 


A session 设置 证 书 验证 过 程 ， 当 请 求 一 个 服务 器 的 证 书 验 证 时 ， 使 用 
proc(hostname, certificate, callback) 调用 proc .调用 callback(true) 来 接收 人 证书， 调用 
callback(false) 来 拒绝 验证 证 书 . 


调用 了 setCertificateverifyProc(null) ， 则 将 会 回复 到 默认 证 书 验 证 过 程 . 


myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, callback) 
if (hostname == 'github.com') 
callback(true); 
elise 
callback(false); 


4); 
EE 





ses.setPermissionRequestHandler (handler) 


e handler Function 
© webContents Object - WebContents 请 求 许可 . 
o permission String - 枚 举 了 'media’, ‘geolocation’, ‘notifications’, 'midiSysex', 
‘pointerLock', ‘fullscreen’. 
o callback Function - 允许 或 禁止 许可 . 


为 对 应 session 许可 请 求 设置 响应 句柄 .调用 callback(true) 接收 许可 ， 调 用 
callback(false) 禁止 许可 . 


session.fromPartition(partition) .setPermissionRequestHandler(function(webContents, permis 


if (webContents.getURL() === host) { 
if (permission == "notifications") { 
callback(false); // denied. 
return; 


} 


callback(true); 
3); 





‘| 


ses.clearHostResolverCache( [callback] ) 





e callback Function (* x) - 操作 结束 调用 . 
清除 主机 解析 缓存 . 


ses.webRequest 
在 其 生命 周期 的 不 同 阶段 ， webRequest API 设置 允许 拦截 并 修改 请 求 内 容 . 


每 个 API 接收 一 可 选 的 filter 和 listener ， 当 API 事件 发 生 的 时 候 使 用 
listener(details) 调用 listener ， details 是 一 个 用 来 描述 请 求 的 对 象 .为 listener 1% 
用 null 则 会 退 定 事件 . 

filter 是 一 个 拥有 urls 属性 的 对 象 ， 这 是 一 个 url 模式 数组 ， 这 用 来 过 滤 掉 不 匹配 指定 
url 模式 的 请 求 .如 果 和 忽略 filter ， 那 么 所 有 请 求 都 将 可 以 成 功 匹配 . 


所 有 事件 的 listener 都 有 一 个 回调 事件 ， 当 listener 完成 它 的 工作 的 时 候 ， 它 将 使 用 一 
个 response 对 象 来 调用 . 


// 将 所 有 请 求 的 代理 都 修改 为 下 列 url. 
var filter = { 
urls: [hetps://—.glthub. coms") 89 3//electnoni. github. ron 


}; 


session.defaultSession.webRequest.onBeforeSendHeaders(filter, function(details, callback) 


details.requestHeaders['User-Agent'] = "MyAgent"; 
callback({cancel: false, requestHeaders: details.requestHeaders}); 


3); 





ses.webRequest .onBeforeRequest([filter, ]listener) 


e filter Object 
e listener Function 


当 一 个 请 求 即 将 开始 的 时 候 ， 使 用 listener(details, callback) 调用 listener . 
e details Object 


o id Integer 
o url String 


© method String 

© resourceType String 

© timestamp Double 

o uploadData Array (可 选 ) 
e callback Function 


uploadData 是 一 个 data 数组 对 象 : 


e data Object 
o bytes Buffer - 被 发 送 的 内 容 . 
o file String - 上 载 文 件 路 径 . 


callback 必须 使 用 一 个 response 对 象 来 调用 : 


e response Object 
o cancel Boolean (可 选 ) 
o redirecturRL String (可 选 ) - 原始 请 求 阻止 发 送 或 完成 ， 而 不 是 重 定向 . 


ses.webRequest .onBeforeSendHeaders([filter, ]listener) 


e filter Object 
e listener Function 


一 旦 请 求 报 文 头 可 用 了 ,在 发 送 HTTP 请 求 的 之 前 ， 使 用 listener(details, callback) 调用 
listener .这 也 许 会 在 服务 器 发 起 一 个 tcp 连接 ， 但 是 在 发 送 任何 http 数据 之 前 发 生 . 


e details Object 

o id Integer 

o url String 

© method String 

© resourceType String 

© timestamp Double 

© requestHeaders Object 
e callback Function 


必须 使 用 一 个 response 对 象 来 调用 callback : 


e response Object 
o cancel Boolean (可 选 ) 
2 requestHeaders Object (可 i) - 如 果 提 供 了 ,将 使 用 这 headers 来 创建 请 求 . 


ses.webRequest .onSendHeaders([filter, ]listener) 


e filter Object 
e listener Function 


在 一 个 请 求 正 在 发 送 到 服务 器 的 时 候 > 使 用 listener(details) 来 调用 listener ， 之 前 
onBeforeSendHeaders 修改 部 分 响应 可 用 ， 同 时 取消 监听 . 


e details Object 
o id Integer 
o url String 
© method String 
© resourceType String 
© timestamp Double 
© requestHeaders Object 


ses.webRequest .onHeadersReceived([filter, ] listener) 


e filter Object 
e listener Function 


4 HTTP 请 求 报 文 头 已 经 到 达 的 时 候 ， 使 用 listener(details, callback) 调用 listener . 


e details Object 

o id String 

o url String 

© method String 

© resourceType String 

© timestamp Double 

© statusLine String 

© statusCode Integer 

O responseHeaders Object 
e callback Function 


必须 使 用 一 个 response 对象 来 调用 callback : 


e response Object 
o cancel Boolean 
o responseHeaders Object (可 选 ) - 如 果 提 供 , 服务 器 将 假定 使 用 这 些 头 来 响应 . 


ses.webRequest .onResponseStarted([filter, ]listener) 


e filter Object 
e listener Function 


当 响 应 body 的 首 字 节 到 达 的 时 候 ， 使 用 listener(details) 调用 listener .对 http 请 求 来 
说 ， 这 意味 着 状态 线 和 响应 头 可 用 了 . 


e details Object 
o id Integer 


o url String 

© method String 

© resourceType String 

© timestamp Double 

© responseHeaders Object 

o fromcache Boolean - 标识 响应 是 否 来 自 磁盘 cache. 
© statuscode Integer 


© statusLine String 


ses.webRequest .onBeforeRedirect([filter, ]listener) 


e filter Object 
e listener Function 


当 服 务 器 的 重 定向 初始 化 正 要 局 动 时 ， 使 用 listener(details) 调用 listener . 


e details Object 
o id String 
o url String 
© method String 
© resourceType String 
© timestamp Double 
© redirectuRL String 
© statusCode Integer 
o ip String (可 选 ) - 请 求 的 真实 服务 器 ip 地 址 
© fromCache Boolean 
© responseHeaders Object 


ses.webRequest .onCompleted([filter, ]listener) 


e filter Object 
e listener Function 


当 请 求 完 成 的 时 候 ， 使 用 listener(details) 调用 listener . 


e details Object 
o id Integer 
o url String 
© method String 
© resourceType String 
o timestamp Double 
© responseHeaders Object 
© fromCache Boolean 


© statusCode Integer 


© statusLine String 


ses.webRequest.onErrorOccurred([filter, ]listener) 


e filter Object 
e listener Function 


当 一 个 错误 发 生 的 时 候 ， 使 用 listener(details) 调用 listener . 


e details Object 
o id Integer 
o url String 
© method String 
© resourceType String 
© timestamp Double 
o fromcache Boolean 


o error String - 错误 描述 . 


webContents 


webContents 是 一 个 事件 发 出 x. 
它 负 责 泻 染 并 控制 网 页 ， 也 是 Browserwindow 对 象 的 属性 .一 个 使 用 webcontents 的 例子 : 
const BrowserWindow = require('electron').BrowserWindow; 


var win = new BrowserWindow({width: 800, height: 1500}); 
win. loadURL("http://github.com"); 


var webContents = win.webContents; 


事件 


webcontents 对 象 可 发 出 下 列 事 件 : 


Event: 'did-finish-load' 


当 寻 航 完 成 时 发 出 事件 ， onload 事件 也 完成 . 


Event: 'did-fail-load' 


e event Event 

e errorcode Integer 

e errorDescription String 
e validatedurL String 


这 个 事件 类 似 did-finish-load ， 但 是 是 在 加 载 失 败 或 取消 加 载 时 发 出 , 例如 ， 
window.stop() 请 求 结束 .错误 代码 的 完整 列表 和 它们 的 含义 都 可 以 在 here 找到 . 
Event: "did-frame-finish-load' 

返回 : 


e event Event 


e isMainFrame Boolean 


4—- frame 导航 完成 的 时 候 发 出 事件 . 


Event: ‘did-start-loading' 


4 tab % spinner 开始 spinning 的 时 候 . 


Event: ‘did-stop-loading' 


当 tab 的 spinner 结束 spinning 的 时 候 . 


Event: 'did-get-response-details' 


e event Event 

e status Boolean 

e newuRL String 

e originalurRL String 

e httpResponseCode Integer 
e requestMethod String 

e referrer String 

e headers Object 


当 有 关 请 求 资 源 的 详细 信息 可 用 的 时 候 发 出 事件 .status 标识 了 socket 链 接 来 下 载 资 源 . 


Event: did-get-redirect-request 


e event Event 

e olduURL String 

e newuRL String 

e isMainFrame Boolean 

e httpResponseCode Integer 
e requestMethod String 

e referrer String 

e headers Object 


当 在 请 求 资源 时 收 到 重 定向 的 时 候 发 出 事件 . 


Event: 'dom-ready' 
返回 : 
e event Event 


448 frame 中 的 文档 加 载 完 成 的 时 候 发 出 事件 . 


Event: 'page-favicon-updated' 
返回 : 


e event Event 
e favicons Array - Array of URLs 


4 page 收 到 图 标 url 的 时 候 发 出 事件 . 


Event: 'new-window' 


e event Event 

e url String 

e frameName String 

e disposition String - 可 为 default , foreground-tab , background-tab , new-window 和 


other . 


e options Object- 创建 新 的 Browserwindow 时 使 用 的 参数 . 


当 page 请 求 打 开 指 定 url 窗口 的 时 候 发 出 事件 .这 可 以 是 通过 window.open 或 一 个 外 部 连接 
如 <a target='_blank'> 发 出 的 请 求 . 


默认 指定 url 的 BrowserWindow 会 被 创建 . 


调用 event.preventDefault() 可 以 用 来 阻止 打开 窗口 . 


Event: ‘will-navigate' 
返回 : 


e event Event 
e url String 


SA PX page 想 要 开始 导航 的 时 候 发 出 事件 . 它 可 在 当 window.location 对 象 改 变 或 用 户 点 
击 page 中 的 链接 的 时 候 发 生 . 


当 使 用 api( 如 webContents.loadURL 和 webContents.back ) 以 编程 方式 来 启动 导航 的 时 候 ， 这 
个 事件 将 不 会 发 出 . 


它 也 不 会 在 页 内 跳 转发 生 ， 例 如 点 击 销 链接 或 更 新 window.location.hash .使 用 
did-navigate-in-page 事件 可 以 达到 目的 . 


调用 event. preventDefault() 可 以 阻止 导航 . 


Event: ‘did-navigate' 


返回 : 


e event Event 
e url String 


当 一 个 导航 结束 时 候 发 出 事件 . 

页 内 跳 转 时 不 会 发 出 这 个 事件 ， 例 如 点 击 锚 链 接 或 更 新 window.location.hash .使 用 
did-navigate-in-page 事件 可 以 达到 目的 . 

Event: ‘did-navigate-in-page’ 

返回 : 


e event Event 
e url String 


当 页 内 导航 发 生 的 时 候 发 出 事件 . 

当 页 内 导航 发 生 的 时 候 ，page 的 url 改变 ， 但 是 不 会 跳出 界面 .例如 当 点 击 锚 链 接 时 或 者 DOM 
的 hashchange 事件 发 生 . 

Event: ‘crashed’ 


H ra RTA ALA TR SE, 


Event: 'plugin-crashed' 
返回 : 


e event Event 
e name String 


e version String 


当 播 件 进程 崩 演 时 候 发 出 事件 . 


Event: destroyed 


当 webcontents 被 删除 的 时 候 发 出 事件 . 


Event: devtools-opened 


当 开 发 者 工具 栏 打开 的 时 候 发 出 事件 . 


Event: 'devtools-closed'’ 


当 开 发 者 工具 栏 关闭 时 候 发 出 事件 


Event: 'devtools-focused' 


当 开 发 者 工具 栏 获得 焦点 或 打开 的 时 候 发 出 事件 


Event: 'certificate-error' 


e event Event 

e url URL 

e error String - The error code 

e certificate Object 
o data Buffer- PEM encoded data 
© issuerName String 


e callback Function 
当 验 证 证 书 或 url 失败 的 时 候 发 出 事件 . 


使 用 方法 类 似 app 的 certificate-error 事件 . 


Event: 'select-client-certificate' 


e event Event 
e url URL 
e certificateList [Objects] 
o data Buffer- PEM encoded data 
© issuerName String - Issuer's Common Name 
e callback Function 


当 请 求 客户 端 证 书 的 时 候 发 出 事件 


使 用 方法 类 似 app 的 select-client-certificate 事件 . 
Event: ‘login’ 
返回 : 


e event Event 


e request Object 
© method String 
o url URL 
o referrer URL 
e authInfo Object 
© isProxy Boolean 
© scheme String 
o host String 
o port Integer 
o realm String 
e callback Function 


当 webContents 想 做 基本 验证 的 时 候 发 出 事件 . 


使 用 方法 类 似 the login event of app. 


Event: 'found-in-page' 
返回 : 


e event Event 
e result Object 
© requestId Integer 
o finalUpdate Boolean - 标识 是 否 还 有 更 多 的 值 可 以 查看 . 
o activeMatchordinal Integer (可 选 ) - 活动 匹配 位 置 
o matches Integer (可 选 ) - 匹配 数量 . 
© selectionarea Object (可 选 ) - 协调 首 个 匹配 位 置 . 


当 使 用 webContents.findinPage 进行 页 内 查找 并 且 找 到 可 用 值得 时 候 发 出 事件 . 


Event: 'media-started-playing' 


当 媒 体 开始 播放 的 时 候 发 出 事件 . 


Event: 'media-paused' 


当 媒 体 停 止 播放 的 时 候 发 出 事件 


Event: "did-change-theme-color 


当 page 的 主题 色 时 候 发 出 事件 .这 通常 由 于 引入 了 一 个 meta 标签 : 


<meta name='theme-color' content='#ff0000'> 


Event: ‘cursor-changed' 
返回 : 


e event Event 

e type String 

e image Nativelmage (可 选 ) 
e scale Float (可 选 ) 


当 和 鼠标 的 类 型 发 生 改 变 的 时 候 发 出 事件 . type 的 参数 可 以 是 default , crosshair , 


pointer , text , wait , help , e-resize , n-resize , ne-resize , nw-resize , s-resize , 
se-resize , Sw-resize , w-resize , ns-resize , ew-resize , nesw-resize , nwse-resize , 
col-resize , row-resize , m-panning , e-panning , n-panning , ne-panning , nw-panning , 
S-panning , se-panning , Sw-panning , w-panning , move , vertical-text , cell, 
context-menu , alias , progress , nodrop , copy , none 


zoom-out , grab , grabbing , custom. 


, not-allowed , zoom-in , 


如 果 type 参数 值 为 ”custom , image 参数 会 在 一 个 NativeImage 中 控制 自 定 义 鼠 标 图 片 ,并 
E scale 会 控制 图 片 的 缩放 比例 . 


实例 方法 
webcontents 对 象 有 如 下 的 实例 方法 : 


webContents.loadURL(url[, options] ) 


e url URL 
e options Object (可 选 ) 
o 


httpReferrer String - A HTTP Referrer url. 
© userAgent String - 产生 请 求 的 用 户 代 理 


o extraHeaders String - YA "in" 分隔 的 额外 头 


在 窗口 中 加 载 url ，url 必须 包含 协议 前 组 ,比如 http:// 或 file:// .如 果 加 载 想 要 忽略 
http 缓存 ， 可 以 使 用 pragna 头 来 达到 目的 . 


const options = {"extraHeaders" : "pragma: no-cache\n"} 
webContents.loadURL(url, options) 


webContents.downloadURL (url) 


e url URL 
初始 化 一 个 指定 url 的 资源 下 载 ， 不 导航 跳 转 ，session 的 will-download 事件 会 触发 . 
webContents .getURL( ) 
返回 当前 page 的 url. 
var win = new BrowserWindow({width: 800, height: 600}); 
win. loadURL("http://github.com"); 
var currentURL = win.webContents.getURL(); 
webContents. getTitle() 
返回 当前 page 的 标题 . 
webContents. IsLoading() 
返回 一 个 布尔 值 ， 标 识 当前 页 是 否 正在 加 载 . 
webContents. isWaitingForResponse( ) 
返回 一 个 布尔 值 ， 标 识 当 前 页 是 否 正 在 等 待 主要 资源 的 第 一 次 响应 . 
webContents.stop() 
停止 还 为 开始 的 导航 . 
webContents.reload() 
重 载 当 前 页 . 
webContents.reloadIgnoringCache( ) 
重 载 当 前 页 ， 忽 略 缓存 . 


webContents.canGoBack() 


Ve 


返回 一 个 布尔 值 ， 标 识 浏览 器 是 否 能 回 到 前 一 个 page. 


webContents.canGoForward() 


Ve 


返回 一 个 布尔 值 ， 标 识 浏览 器 是 否 能 前 往 下 一 个 page. 


webContents.canGoToOffset (offset ) 


e offset Integer 


返回 一 个 布尔 值 ， 标 识 浏览 器 是 否 能 前 往 指定 offset 的 page. 
webContents.clearHistory() 
清除 导航 历史 . 


webContents goBack( ) 


让 浏览 器 回 退 到 前 一 个 page. 


webCcontents .goForward () 


让 浏览 器 回 前 往 下 一 个 page. 
webContents.goToIndex(index) 


e index Integer 


让 浏览 器 回 前 往 指定 index page. 
webContents. goToOffset (offset) 


e offset Integer 


导航 到 相对 于 当前 页 的 偏 移 位 置 页 . 


webContents.isCrashed() 


webContents.setUserAgent (userAgent ) 


e userAgent String 


重 写 本 页 用 户 代 理 . 


webContents.getUserAgent() 


返回 一 个 string ， 标识 本 页 用 户 代 理 信息 . 


webContents. insertCSS(css) 


e css String 


为 当前 页 插入 css. 


webContents.executeJavaScript(code[, userGesture, callback] ) 


èe code String 


e userGesture Boolean (可 选 ) 


e callback Function (可 选 ) - 脚本 执行 完成 后 调用 的 回调 函数 . 


o result 


评估 page 代码 . 


浏览 器 窗口 中 的 一 些 HTML API， 例 如 requestFullscreen ， 只 能 被 用 户 手 势 请 求 .设置 
userGesture 为 true 可 以 取消 这 个 限制 . 


webContents.setAudioMuted (muted ) 


e muted Boolean 


减缓 当前 也 的 audio 的 播放 速度 


webContents. IsAudioMuted () 


返回 一 个 布尔 值 ， 标 识 当 前 页 是 


webContents.undo() 
执行 网 页 的 编辑 undo . 
webContents. redo() 
执行 网 页 的 编辑 命令 redo . 
webContents.cut() 

执行 网 页 的 编辑 命令 cut . 

webContents.copy( ) 


执行 网 页 的 编辑 命令 copy . 


webContents. paste() 


执行 网 页 的 编辑 命令 paste . 


TRA T audio 的 播放 速度 


webContents. pasteAndMatchStyle( ) 


执行 网 页 的 编辑 命令 pasteAndMatchstyle . 


webContents. delete() 


执行 网 页 的 编辑 命令 delete . 


webContents.selectAll() 


执行 网 页 的 编辑 命令 selectall . 


webContents.unselect() 


执行 网 页 的 编辑 命令 unselect . 


webContents.replace(text) 


e text String 


执行 网 页 的 编辑 命令 replace . 


webContents. replaceMisspelling( text ) 


e text String 


执行 网 页 的 编辑 命令 replaceMisspelling . 


webContents. insertText (text) 


e text String 


插入 text 到 获得 了 焦点 的 元 素 . 


webCcontents .findInPage(text[，options] ) 


e text String- 查找 内 容 , 不 能 为 空 . 
e options Object (可 选 ) 
o forward Boolean- 是 否 向 前 或 向 后 查找 , 默认 为 true. 
o findNext Boolean - 当前 操作 是 否 是 第 一 次 查找 或 下 一 次 查找 , 默认 为 false. 
o matchcase Boolean - 查找 是 否 区 分 大 小 写 , RUA false. 
o wordstart Boolean -是 否 仅 以 首 字母 查找 . 默认 为 false. 
© medialCapitalAswordstart Boolean - 是 否 结合 wordstart ,如 果 匹 配 是 大 写字 母 开 
头 ， 后 面 接 小 写字 母 或 无 字母 ， 那 么 就 接受 这 个 词 中 匹配 .接受 几 个 其 它 的 合成 词 匹 


配 , 默认 为 false . 
发 起 请 求 ， 在 网 页 中 查找 所 有 与 text 相 匹 配 的 项 ， 并 且 返 回 一 个 Integer 来 表示 这 个 请 求 
用 的 请 求 Id. 这 个 请 求 结果 可 以 通过 订阅 found-in-page 事件 来 取得 


webContents.stopFindInPage(action) 


e action String - 指定 一 个 行为 来 接替 停止 webcontents.findInPage 请 求 . 
o clearSelection -转变 为 一 个 普通 的 selection. 
© keepSelection - 清除 selection. 
© activateSelection - 获取 焦点 并 点 击 selection node. 


使 用 给 定 的 action 来 为 webcontents 停止 任何 findInPage 请 求 . 


webContents.on('found-in-page', function(event, result) { 
if (result.finalUpdate) 
webContents.stopFindInPage("clearSelection"); 


3); 


const requestId = webContents.findInPage("api"); 


webContents.hasServiceworker (callback) 


e callback Function 


检查 是 否 有 任何 ServiceWorker 注册 了 ， 并 且 返 回 一 个 布尔 值 ， 来 作为 callback 响应 的 标 


webContents.unregisterServiceworker (callback) 


e callback Function 


如 果 存 在 任何 ServiceWorker ， 则 全 部 注销 ， 并 且 当 JS 承诺 执行 行 或 JS 拒绝 执行 而 失败 的 时 
候 ， 返 回 一 个 布尔 值 ， 它 标识 了 相应 的 callback . 


webContents. print( [options] ) 


e options Object (可 选 ) 
o silent Boolean -不 需要 请 求 用 户 的 打印 设置 . 默认 为 false. 
© printBackground Boolean -打印 背景 和 网 页 图 片 . 默认 为 false. 


打印 窗口 的 网 页 . 当 设置 silent A false 的 时 候 ，Electron 将 使 用 系统 默认 的 打印 机 和 打 
印 方式 来 打印 . 


在 网 页 中 调用 window.print() 和 调用 
webContents.print({silent: false, printBackground: false}) 具有 相 同 的 作用 . 


注意 : 在 Windows, 打印 API 依赖 于 pdf.d11 . 如 果 你 的 应 用 不 使 用 任何 的 打印 , 你 可 以 安全 
删除 pdf.dl1 来 减少 二 进 制 文件 的 Size. 


webContents.printToPDF(options, callback) 


e options Object 
o marginsType Integer - 指定 使 用 的 margin type. 默认 margin 使 用 0, % margin 使 用 
1, 最 小 化 margin 使 用 2. 
o pageSize String - 指定 生成 的 PDF 文件 的 page size. 可 以 是 A3, A4, A5, Legal, 
Letter 和 Tabloid 
© printBackground Boolean - 是 否 打 印 css 背景 . 
o printSelectiononly Boolean - 是 否 只 打印 选中 的 部 分 . 
o landscape Boolean - landscape 为 true , portrait 为 false . 
e callback Function 


打印 窗口 的 网 页 为 pdf ， 使 用 Chromium 预览 打印 的 自 定义 设置 . 


完成 时 使 用 callback(error, data) 调用 callback . data 是 一 个 Buffer ， 包 含 了 生成 的 
pdf 数据 . 


默认 ， 空 的 options BALA : 


marginsType: 0, 
printBackground: false, 
printSelectionOnly: false, 
landscape: false 


const BrowserWindow = require('electron').BrowserWindow; 
const fs = require('fs'); 


var win = new BrowserWindow({width: 800, height: 600}); 
win. loadURL("http://github.com"); 


win.webContents.on("did-finish-load", function() { 
// Use default printing options 
win.webContents.printToPDF({}, function(error, data) { 
if (error) throw error; 
fs.writeFile("/tmp/print.pdf", data, function(error) { 
if (error) 
throw error; 
console.log("Write PDF successfully."); 
}) 
}) 
}); 


webContents.addworkSpace(path) 


e path String 


添加 指定 的 路 径 给 开发 者 工具 栏 的 workspace. #2 DevTools 创建 之 后 使 用 它 : 


mainWindow.webContents.on('devtools-opened', function() { 
mainWindow.webContents.addWorkSpace(_ dirname); 


3); 


webContents. removeWorkSpace(path) 
e path String 

MARA LAE workspace 删除 指定 的 路 径 . 
webContents.openDevTools( [options]) 


e options Object (可 选 ) 
o detach Boolean -在 一 个 新 窗口 打开 开发 者 工具 栏 


打开 开发 者 工具 栏 . 
webContents.closeDevTools( ) 


关闭 开发 者 工具 栏 . 


webContents .isDevToolsOpened() 


返回 布尔 值 ， 开 发 者 工具 栏 是 否 打开 . 


webContents.isDevToolsFocused( ) 


返回 布尔 值 ， 开 发 者 工具 栏 视图 是 否 获得 焦点 . 


webContents.toggleDevTools( ) 


Toggles 开发 者 工具 . 


webContents.inspectElement (x, y) 


e x Integer 
e y Integer 


在 ( x，y ) 开始 检测 元 素 . 


webContents. inspectServiceworker ( ) 


为 service worker 上 下 文 打 开 开 发 者 工具 栏 . 


webContents.send(channel[, argi][, arg2][, -.-]) 


e channel String 
e arg (可 选 ) 


通过 channel 发 送 异 步 消息 给 泻 染 进程 ， 你 也 可 发 送 任意 的 参数 .参数 应 该 在 ISON 内 部 序 
列 化 ， 并 且 此 后 没有 函数 或 原形 链 被 包括 了 . 


Hv E $, 
var window = null; 
app.on('ready', function() { 
window = new BrowserWindow({width: 800, height: 600}); 
window.loadURL('file://' + _ dirname + '/index.html'); 
window.webContents.on('did-finish-load', function() { 
window.webContents.send('ping', 'whoooooooh!'); 


}); 
}); 


<!-- index.html --> 
<html> 
<body> 
<script> 
require('electron').ipcRenderer.on('ping', function(event, message) { 
console.log(message); // Prints "whoooooooh!" 


3); 


</body> 
</html> 


webContents.enableDeviceEmulation(parameters) 


parameters Object, properties: 


e screenPosition String - 指定 需要 模拟 的 屏幕 (AK : desktop ) 
o desktop 
o mobile 
e screenSize Object - 设置 模拟 屏幕 size (screenPosition == mobile) 
o width Integer - 设置 模拟 屏幕 width 
o height Integer - 设置 模拟 屏幕 height 
e viewPosition Object - 在 屏幕 放置 view (screenPosition == mobile) (默认 : 
{x: 0, y: 0} ) 
o x Integer -设置 偏 移 左上 角 的 X 轴 
o y Integer -设置 偏 移 左上 角 的 y 轴 
e devicescaleFactor Integer - 设置 设备 比例 因子 (如 果 为 0， 默 认为 原始 屏幕 比例 ) (默认 : 
o ) 


e viewsize Object - 设置 模拟 视图 size ( 空 表示 不 禾 盖 ) 


o width Integer -设置 模拟 视图 width 
o height Integer - 设置 模拟 视图 height 
e fitToview Boolean - 如 果 有 必要 的 话 ， 是 否 把 模拟 视图 按 比 例 缩放 来 适应 可 用 空间 (R 
th: false ) 
e offset Object- 可 用 空间 内 的 模拟 视图 偏 移 (不 在 适应 模式 ) (默认 : {x: 0, y: oF ) 
o x Float- 设置 相对 左上 和 角 的 X 轴 偏 移 值 
o y Float- 设置 相对 左上 和 角 的 y 轴 偏 移 值 
e scale Float- 可 用 空间 内 的 模拟 视图 偏 移 (不 在 适应 视图 模式 ) (默认 : 1 ) 


使 用 给 定 的 参数 来 开启 设备 模拟 . 


webContents.disableDeviceEmulation() 


使 用 webContents.enableDeviceEmulation 关闭 设备 模拟 . 


webContents.sendInputEvent (event) 


e event Object 
o type String (必需 ) - 事件 类 型 ， 可 以 是 mouseDown , mouseUp , mouseEnter , 
mouseLeave , contextMenu , mouseWheel , mouseMove , keyDown , keyUp , char . 
o modifiers Array - 事件 的 modifiers 数组 , 可 以 是 include shift , control, alt , 
meta , isKeypad ， isAutoRepeat , leftButtonDown , middleButtonDown , 


rightButtonDown , capsLock , numLock , left , right. 

向 page 发 送 一 个 输入 event . 
对 键盘 事件 来 说 ， event 对 象 还 有 如 下 属性 : 

e keycode String (必需 ) - 特点 是 将 作为 键盘 事件 发 送 . 可 用 的 key codes Accelerator. 
对 鼠标 事件 来 说 ， event 对 象 还 有 如 下 属性 : 

e x Integer (required) 

e y Integer (required) 

e button String - button 按 下 , 可 以 是 left, middle , right 

e globalx Integer 

e globaly Integer 

e movementx Integer 


e movementy Integer 


e clickcount Integer 
对 鼠标 滚轮 事件 来 说 ， event 对 象 还 有 如 下 属性 : 


e deltax Integer 
e deltay Integer 


e wheelTicksx Integer 

e wheelTicksY Integer 

e accelerationRatiox Integer 

e accelerationRatioy Integer 

e hasPreciseScrollingDeltas Boolean 
e canScroll Boolean 


webContents.beginFrameSubscription(callback) 


e callback Function 


开始 订阅 提交 事件 和 捕获 数据 帧 ， 当 有 提交 事件 时 ， 使 用 callback(frameBuffer) 调用 
callback . 


frameBuffer 是 一 个 包含 原始 像素 数据 的 Buffer ,像素 数据 是 按照 32bit BGRA 格式 有 效 存 
储 的 ， 但 是 实际 情况 是 取决 于 处 理 器 的 字 节 顺序 的 (大 多 数 的 处 理 器 是 存放 小 端 序 的 ， 如 果 是 
在 大 端 序 的 处 理 器 上 ， 数 据 是 32bit ARGB 格式 ). 


webContents.endFrameSubscription() 


停止 订阅 帧 提交 事件 . 


webContents.savePage(fullPath, saveType, callback) 


e fullpath String - 文件 的 完整 路 径 . 
e saveType String - 指定 保存 类 型 . 
© HTMLonly - 只 保存 html. 
© HTMLComplete - 保存 整个 page 内 容 . 
o MHTML -保存 完整 的 html 为 MHTML. 
e callback Function - function(error) {}. 
o error Error 


如 果 保 存 界 面 过 程 初 始 化 成 功 ， 返 回 true. 


win. loadURL('https://github.com'); 


win.webContents.on('did-finish-load', function() { 
win.webContents.savePage('/tmp/test.html', 'HTMLComplete', function(error) { 
if (!error) 
console.log("Save page successfully"); 


Webcontents 对 象 也 有 下 列 属性 : 


webContents.session 


返回 这 个 webcontents 使 用 的 session WR. 


webContents.hostWebContents 


返回 这 个 webContents 的 父 webContents 


webContents.devToolswebContents 


获取 这 个 webcontents 的 开发 者 工具 栏 的 Webcontents 


注意 : 用 户 不 可 保存 这 个 对 象 ， 因 为 当 开 发 者 工具 栏 关 闭 的 时 候 它 的 值 为 null 


webContents. debugger 


调试 API 为 remote debugging protocol 提供 交替 传送 . 


ery f 
win.webContents.debugger.attach("1.1"); 


} catch(err) { 
console.log("Debugger attach failed : ", err); 


}; 


win.webContents.debugger.on('detach', function(event, reason) { 
console.log("Debugger detached due to : ", reason); 


}); 


win.webContents.debugger.on('message', function(event, method, params) { 
if (method == "Network.requestWillBeSent") { 
if (params.request.url == "https://www.github.com") 
win.webContents.debugger .detach(); 


} 
}) 


win.webContents.debugger.sendCommand("Network.enable"); 


webContents.debugger .attach([protocolVersion]) 
e protocolversion String (7 2) - 请 求 调试 协议 版 本 . 

添加 webcontents 调试 . 
webContents. debugger .IsAttached () 

返回 一 个 布尔 值 ， 标 识 是 否 已 经 给 webcontents 添加 了 调试 . 
webContents. debugger .detach() 


删除 webcontents 调试 . 


webContents. debugger .sendCommand(method[, commandParams, callback] ) 


e method String - 方法 名 , 应 该 是 由 远程 调试 协议 定义 的 方法 . 
e commandParams Object (可 选 ) - 请 求 参 数 为 JSON HR. 
e callback Function (可 选 ) - Response 
o error Object- 错误 消息 ， 标 识 命令 失败 . 
o result Object - 回复 在 远程 调试 协议 中 由 'returns' 属 性 定义 的 命令 描述 


发 送 给 定 命令 给 调试 目标 . 


Event: ‘detach’ 


e event Event 
e reason String - 拆 分 调试 器 原因 . 


在 调试 session 结束 时 发 出 事件 .这 在 webcontents 关闭 时 或 webcontents 请 求 开 发 者 工具 
栏 时 发 生 . 
Event: 'message' 


e event Event 
e method String -方法 名 . 
e params Object -在 远程 调试 协议 中 由 "parameters' 属性 定义 的 事件 参数 


每 当 调 试 目标 发 出 事件 时 发 出 . 


Tray 


用 一 个 tray 来 表示 一 个 图 标 ,这 个 图 标 处 于 正在 运行 的 系统 的 通知 区 ， 通 常 被 添加 到 一 个 
context menu 上 . 


const electron = require('electron'); 
const app = electron.app; 

const Menu electron.Menu; 

const Tray electron.Tray; 


var appIcon = null; 
app.on('ready', function(){ 
appIcon = new Tray('/path/to/my/icon'); 
var contextMenu = Menu.buildFromTemplate([ 
{ label: 'Item1i', type: 'radio' }, 
{ label: 'Item2', type: 'radio' }, 
{ label: 'Item3', type: 'radio', checked: true y, 
{ label: 'Item4', type: 'radio' } 


]); 
appIcon.setToolTip('This is my application.'); 
appIcon.setContextMenu(contextMenu); 


3); 


平台 限制 : 


e 在 Linux ， 如 果 支 持 应 用 指示 器 则 使 用 它 ， 否 则 使 用 GtkstatusIcon 代替 . 

。 在 Linux， 配 置 了 只 有 有 了 应 用 指示 器 的 支持 , 你 必须 安装 libappindicator1 来 让 tray 
icon 执行 . 

。 应 用 指示 器 只 有 在 它 拥 有 context menu 时 才 会 显示 . 

e 当 在 linux 上 使 用 了 应 用 指示 器 ， 将 忽略 点 击 事件 . 

e 在 Linux， 为 了 让 单独 的 MenuItem 起 效 ， 需 要 再 次 调用 setcontextmenu .例如 : 


contextMenu.items[2].checked = false; 
appIcon.setContextMenu(contextMenu) ; 


如 果 想 在 所 有 平台 保持 完全 相同 的 行为 ， 不 应 该 依赖 点 击 事件 ， 而 是 一 直 将 一 个 context 
menu 添加 到 tray icon. 


Class: Tray 
Tray 是 一 个 事件 发 出 者 . 


new Tray(image) 


e image Nativelmage 


创建 一 个 与 image 相关 的 icon. 


事件 


Tray 模块 可 发 出 下 列 事件 : 


注意 : 一 些 事 件 只 能 在 特定 的 os 中 运行 ， 已 经 标明 . 


Event: ‘click’ 


e event Event 
© altkey Boolean 
© shiftkey Boolean 
© ctrikey Boolean 
o metakey Boolean 
e bounds Object - tray icon 的 bounds. 
o x Integer 
o y Integer 
o width Integer 
© height Integer 


4 tray icon 被 点 击 的 时 候 发 出 事件 . 


注意 : bounds 只 在 OS X 和 Windows 上 起 效 . 


Event: 'right-click" OS X Windows 


e event Event 
o altkey Boolean 
o shiftkey Boolean 
© ctrlKey Boolean 
o metakey Boolean 
e bounds Object - tray icon 的 bounds. 
o x Integer 
o y Integer 
o width Integer 
o height Integer 


% tray icon 被 鼠标 右键 点 击 的 时 候 发 出 事件 . 


Event: 'double-click' OS X Windows 


e event Event 
o altkey Boolean 


© shiftkey Boolean 

© ctrlKey Boolean 

© metakey Boolean 

e bounds Object - tray icon 的 bounds. 

o x Integer 

o y Integer 

o width Integer 

© height Integer 


% tray icon 被 双击 的 时 候 发 出 事件 . 
Event: 'balloon-show' Windows 


Stray 气泡 显示 的 时 候 发 出 事件 . 


Event: ‘balloon-click’' Windows 


Stray 气泡 被 点 击 的 时 候 发 出 事件 . 


Event: balloon-closed Windows 


Stray 气泡 关闭 的 时 候 发 出 事件 ， 因 为 超时 或 人 为 关闭 . 


Event: ‘drop’ OS X 


% tray icon 上 的 任何 可 拖 动 项 被 删除 的 时 候 发 出 事件 . 


Event: ‘drop-files' OS X 


@ event 


e files Array - 已 删除 文件 的 路 径 . 
当 tray icon 上 的 可 拖 动 文件 被 删除 的 时 候 发 出 事件 . 
Event: 'drag-enter' OS X 


当 一 个 拖 动 操作 进入 tray icon 的 时 候 发 出 事件 . 


Event: 'drag-leave' OS X 


当 一 个 拖 动 操作 离开 tray icon 的 时 候 发 出 事件 . Emitted when a drag operation exits the tray 
icon. 


Event: 'drag-end' OS X 

当 一 个 拖 动 操作 在 tray icon 上 或 其 它 地 方 停止 拖 动 的 时 候 发 出 事件 . 
FAK 

Tray 模块 有 以 下 方法 : 
Note: 一 些 方法 只 能 在 特定 的 0S 中 运行 ， 已 经 标明 . 
Tray.destroy() 
立刻 删除 tray icon. 

Tray .setImage(image) 

e image Nativelmage 


让 image 4 tray icon 关联 起 来 . 


Tray.setPressedImage(image) OS X 

e image Nativelmage 
当 在 OS X 上 按压 tray icon 的 时 候 ， 让 image 4 tray icon 关联 起 来 . 
Tray.setToolTip(toolTip) 


e tooltip String 


A tray icon 7&4 hover text. 


Tray.setTitle(title) OSX 
e title String 


在 状态 栏 沿 着 tray icon 设置 标题 . 


Tray.setHighlightMode(highlight) OS X 
e highlight Boolean 


当 tray icon 被 点 击 的 时 候 ， 是 否 设置 它 的 背景 色 变 为 高 亮 (blue). 默 认为 true. 


Tray.displayBalloon(options) Windows 


e options Object 
o icon Nativelmage 
o title String 


o content String 


展示 一 个 tray balloon. 


Tray.popUpContextMenu( [menu, position]) OS X Windows 


e menu Menu (optional) 

e position Object (72%) - 上 托 位 置 . 
o x Integer 
o y Integer 


M tray icon 46 context menu. 当 划 过 menu 的 时 候 ， menu 显示 ， 代 替 tray 的 context 
menu . 


position 只 在 windows 上 可 用 ， 默 认为 (0, 0). 
Tray .setContextMenu (menu) 


e menu Menu 


为 这 个 icon 设置 context menu . 


WE RUA (AR) 内 可 用 的 模块 


desktopCapturer 


desktopCapturer 模块 可 用 来 获取 可 用 资源 ， 这 个 资源 可 通过 getUserMedia 捕获 得 到 . 


A k we su tH $2 q 


var desktopCapturer = require('electron').desktopCapturer; 


desktopCapturer .getSources({types: ['window', 'screen']}, function(error, sources) { 
if (error) throw error; 
for (var i = 0; i < sources.length; ++i) { 
if (sources[i].name == "Electron") { 
navigator .webkitGetUserMedia({ 
audio: false, 
video: { 
mandatory: { 
chromeMediaSource: '‘desktop', 
chromeMediaSourceld: sources[i].id, 
minWidth: 1280, 
maxWidth: 1280, 
minHeight: 720, 
maxHeight: 720 


} 
}, gotStream, getUserMediaError); 
reeurn; 
} 
} 
}); 


function gotStream(stream) { 
document.querySelector('video').srce = URL.createObjectURL(stream) ; 


} 


function getUserMediaError(e) { 
console.log( 'getUserMediaError'); 


} 


当 调 用 navigator .webkitGetUserMedia 时 创建 一 个 约束 对 象 ， 如 果 使 用 desktopCapturer 的 


资源 ， 必 须 设置 chromeMediasource A "desktop" ? 并 且 audio A false. 


如 果 你 想 捕获 整个 桌面 的 audio 和 video ， 你 可 以 设置 chromeMediaSource 为 "screen" ， 和 
audio A true . 当 使 用 这 个 方法 的 时 候 2 不 可 以 指定 一 个 chromeMediaSourceld . 

方法 

desktopCapturer 模块 有 如 下 方法 : 


desktopCapturer.getSources(options, callback) 


e options Object 
o types Array - 一 个 String 数组 ， 列 出 了 可 以 捕获 的 桌面 资源 类 型 , 可 用 类 型 为 


screen 和 window . 


© thumbnailsize Object (可 选 ) - 建议 缩 略 可 被 缩放 的 size, 默认 为 
{width: 150, height: 150} . 
e callback Function 


发 起 一 个 请 求 2 获取 所 有 桌面 资源 ， 当 请 求 完 成 的 时 候 使 用 callback(error, sources) 调用 
callback . 
sources 是 一 个 Source 对 象 数 组 , 每 个 source 表示 了 一 个 捕获 的 屏幕 或 单独 窗口 ， 并 且 
有 如 下 属性 : 
e id String -在 navigator.webkitGetUserMedia 中 使 用 的 捕获 窗口 或 屏幕 的 id .格式 为 
window:XX #4 screen:Xx ， XX 是 一 个 随机 数 . 
e name String - 捕获 窗口 或 屏幕 的 描述 名 . 如 果 资 源 为 屏幕 ， 名 字 为 Entire screen 或 
Screen <index> ; 如 果 资 源 为 窗口 , 名字 为 窗口 的 标题 . 
。 thumbnail Nativelmage - 缩 略 图 . 


注意 : 不 能 保证 source. thumbnail 的 size 和 options 中 的 thumnbailSize 一 直 一 致 . 它 也 
取决 于 屏幕 或 窗口 的 缩放 比例. 


ipcRenderer 


ipcRenderer 模块 是 一 个 EventEmitter 类 的 实例 . 它 提供 了 有 限 的 方法 ， 你 可 以 从 浑 染 进程 
向 主 进程 发 送 同步 或 异步 消息 . 也 可 以 收 到 主 进程 的 相应 . 


查看 ipcMain 代码 例子 . 


消息 监听 
ipcRenderer 模块 有 下 列 方法 来 监听 事件 : 


ipcRenderer.on(channel, listener) 


e channel String 
e listener Function 


监听 channel ; 当 有 新 消 息 到 达 ， 使 用 listener(event, args...) 调用 listener . 


ipcRenderer.once(channel, listener) 


e channel String 
e listener Function 


为 这 个 事件 添加 一 个 一 次 性 listener A.A listener 将 在 下 一 次 有 新 消 息 被 发 送 到 
channel 的 时 候 被 请 求 调 用 ， 之 后 就 被 删除 了 . 


ipcRenderer.removeListener(channel, listener ) 


e channel String 
e listener Function 


从 指定 的 channel 中 的 监听 者 数组 删除 指定 的 listener . 


ipcRenderer .removeAllListeners([channel]) 


e channel String (optional) 


删 除 所 有 的 监听 者 ? 或 者 删除 指定 channel 中 的 全 部 . 


发 送 消息 


ipcRenderer 模块 有 如 下 方法 来 发 送 消 息 : 


ipcRenderer.send(channel[, argi][, arg2][, ...]) 


e channel String 
© arg (可 选 ) 


通过 channel 向 主 进 程 发 送 异 步 ; 消息 Á, > 也 可 以 发 送 任意 参 数 .参数 会 被 JSON 序 列 化 ， 之 后 就 
不 会 包含 函数 或 原型 链 . 


主 进程 通过 使 用 ipcMain 模块 来 监听 channel ， 从 而 处 理 消息 . 


ipcRenderer.sendSync(channel[, argi][, arg2][, ...]) 


e channel String 
e arg (可 选 ) 


通过 channel 向 主 进 程 发 送 同步 消息 ， 也 可 以 发 送 任意 参数 .参数 会 被 JSON 序 列 化 ， 之 后 就 
不 会 包含 函数 或 原型 链 . 


主 进 程 通过 使 用 ipcMain 模块 来 监听 channel ， 从 而 处 理 消息 ， 通过 event.returnValue 来 
响应 . 


注意 : 发 送 同步 消息 将 会 阻塞 整个 泻 染 进程 ,除非 你 你 在 做 什么 ， 否 则 就 永远 不 要 用 它 . 
ipcRenderer.sendToHost(channel[, argi][, arg2][, ...]) 


e channel String 
© arg (可 选 ) 


类 似 ipcRenderer.send ， 但 是 它 的 事件 将 发 往 host page 的 <webview> 元 素 ， 而 不 是 主 进 
程 . 


remote 


remote 模块 提供 了 一 种 在 泻 染 进程 《网 页 ) 和 主 进程 之 间 进 行进 程 间 通讯 (IPC) 的 简便 途 


4 
径 。 


Electron 中 , 与 GUI 相关 的 模块 (如 dialog, menu 等 ) 只 存在 于 主 进程 ， 而 不 在 泻 染 进程 中 
。 为 了 能 从 浑 染 进程 中 使 用 它们 ， 需 要 用 ipe 模块 来 给 主 进程 发 送 进程 间 消 息 。 使 用 

remote 模块 ， 可 以 调用 主 进 程 对 象 的 方法 ， a 进程 间 消 息 ， 这 类 似 于 Java 
的 RMI。 下 面 是 从 泻 染 进程 创建 一 个 浏览 器 窗口 的 例子 


const remote = require('electron').remote; 
const BrowserWindow = remote.BrowserWindow; 


var win = new BrowserWindow({ width: 800, height: 600 }); 
win. loadURL('https://github.com'); 


注意 : 反 向 操作 〈 从 主 进 程 访问 泻 染 进程 ) ， 可 以 使 用 webContents.executeJavascript. 


远程 对 象 


remote 模块 返回 的 每 个 对 象 ( 包括 函数 ) 都 代表 了 主 进程 中 的 一 个 对 象 (我 们 称 之 为 远程 对 
得 或 者 远程 函数 ) 。 当 调 用 远程 对 象 的 方法 、 执 行 远程 函数 或 者 使 用 远程 构造 器 (BAR) 创 
建新 对 象 时 ， 其 实 就 是 在 发 送 同步 的 进程 间 消 息 。 


在 上 面 的 例 | 子 中 ? BrowserWindow 和 win 都 是 远 元 程 对 象 ? 然而 new BrowserWindow 并 没有 
在 泻 染 进程 中 创建 Browserwindow He 而 是 在 主 进程 中 创建 了 Browserwindow 对 象 ， 并 在 
泻 染 进程 中 返回 了 对 应 的 远程 对 象 ， 即 win 对 象 。 


请 注意 只 有 可 枚 举 属性 才能 通过 remote 进行 访问 . 


远程 对 象 的 生命 周期 


Electron 确保 在 泻 业 进程 中 的 远程 对 象 存在 (RAEI RARER) ， 那 主 进程 中 的 
对 应 对 象 也 不 会 被 释放 。 当 远 程 对 外 被 垃圾 收集 之 后 ， 主 进程 中 的 对 应 对 象 才 会 被 取消 关 
联 o 


如 果 远 程 对 象 在 演 染 进程 港 露 了 ( 即 ， 存 在 茶 个 表 中 但 永远 不 会 释放 ) ， 那 么 主 进程 中 的 对 
应 对 葵 也 一 样 会 泄露 ， 所 以 你 必须 小 心 不 要 泄露 了 远程 对 象 。|fthe remote object is leaked 
in the renderer process (e.g. stored in a map but never freed), the corresponding object in 
the main process will also be leaked, so you should be very careful not to leak remote 
objects. 


不 过 ， 主 要 的 值 类 型 如 字符 串 和 数字 ， 是 传递 的 副本 。 


进程 传递 回调 防 数 


在 主 进程 中 的 代码 可 以 从 演 染 进程 remote 模块 一 一 中 接受 回调 函数 ， 但 是 使 用 这 个 功能 
的 时 候 必须 非常 非常 小 心 。Code in the main process can accept callbacks from the renderer 





- for instance the remote module - but you should be extremely careful when using this 
feature. 


ae ， 为 了 避免 死 锁 ， 传 递 给 主 进 程 的 回调 函数 会 进行 异步 调用 。 所 以 不 能 期 望 主 进 程 来 获 

得 传递 过 去 的 回调 函数 的 返 on o First, in order to avoid deadlocks, the callbacks passed to 
the main process are called asynchronously. You should not expect the main process to get 
the return value of the passed callbacks. 


比如 ， 你 不 能 主 进程 中 给 Array.map 传递 来 自 泻 染 进程 的 函数 。 


// 主 进程 mapNumbers.js 

exports.withRendererCallback = function(mapper) { 
return [1,2,3].map(mapper ); 

} 

exports.withLocalCallback = function() { 


return exports.mapNumbers(function(x) { 
return X E I 


3); 
} 


// 演 染 进程 
var mapNumbers = require("remote").require("./mapNumbers"); 


var withRendererCb = mapNumbers.withRendererCallback(function(x) { 
return x + 1; 


}) 


var withLocalCb = mapNumbers.withLocalcallback() 


console.log(withRendererCb, withLocalCb) // [true, true, true], [2, 3, 4] 
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数 的 返回 值 不 同 。 

其 次 ， 传 递 给 主 进程 的 函数 会 持续 到 主 进程 对 他 们 进行 垃圾 回收 。 


例如 ， 下 面 的 代码 第 一 眼看 上 去 毫 无 问题 。 给 远程 对 象 的 close 事件 绑 定 了 一 个 回调 函数 : 


remote.getCurrentWindow().on('close', function() { 
// blabla... 


}); 


但 记 住 主 进程 会 一 直 保 持 对 这 个 回调 函数 的 引用 ， 除 非 明 确 的 纯 载 它 。 如 果 不 纯 载 ， 每 次 重 
新 载 入 窗口 都 会 再 次 绑 定 ， 这 样 每 次 重启 就 会 泄露 一 个 回调 函数 。 


更 严重 的 是 ， 由 于 前 面 安 装 了 回调 函数 的 上 下 文 已 经 被 释放 ， 所 以 当主 进程 的 close SHAK 
发 的 时 候 ， 会 抛 出 异常 。 


了 避免 这 个 问题 ， 要 确保 对 传递 给 主 进程 的 泻 染 器 的 回调 函数 进行 清理 。 可 以 清理 事件 处 
e AITON R A EaR h a R R AA P g A hA o 


访问 主 进程 中 的 内 置 


在 主 进程 中 的 内 置 模块 已 经 被 添加 为 remote 模块 中 的 属性 ， 所 以 可 以 直接 像 使 
用 electron 模块 一 样 直接 使 用 它们 。 


const app = remote.app; 


方法 
remote 模块 有 以 下 方法 : 


remote ,require(module ) 


e module String 


返回 在 主 进程 中 执行 require(module) 所 返回 的 对 象 。 


remote .getCurrentWindow( ) 
返回 该 网 页 所 属 的 Browserwindow 对 象 。 
remote .getCurrentWebContents() 


返回 该 网 页 的 webcontents 对 象 


remote .getGlobal(name) 

e name String 

返回 在 主 进 程 中 名 为 name 的 全 局 变量 ( 即 global[name] ) ° 
remote .process 


返回 主 进程 中 的 process 对 象 等 同 于 remote.getGlobal('process') 但 是 有 缓存 o 
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webFrame 


web-frame 模块 允许 你 自 定 义 如 何 泻 染 当前 网 页 
例子 ， 放 大 当前 页 到 200%. 


var webFrame = require('electron').webFrame; 


webFrame.setZoomFactor(2); 
方法 
web -frame 模块 有 如 下 方法 : 


webFrame .setZoomFactor (factor) 


e factor Number - 缩放 参数 . 


将 缩放 参数 修改 为 指定 的 参数 值 .缩放 参数 是 百分制 的 ， 所 以 300% = 3.0. 


webFrame.getZoomFactor ( ) 


返回 当前 缩放 参数 值 . 


webFrame .setZoomLevel(level) 


e level Number - 缩放 水 平 


将 缩放 水 平 修改 为 指定 的 水 平 值 . 原始 size 为 0， 并 且 每 次 增长 都 表示 放大 20% 或 缩小 
20%， 默 认 限 制 为 原始 size 的 300% 到 50% 之 间 . 


webFrame.getZoomLevel() 
返回 当前 缩放 水 平 值 . 
e 


webFrame.setZoomLevelLimits(minimumLevel, maximumLevel ) 


minimumLevel Number 


e maximumLevel Number 


设置 缩放 水 平 的 最 大 值 和 最 小 值 . 


webFrame.setSpellCheckProvider(language, autoCorrectWord, pr 


e language String 
e autoCorrectword Boolean 
e provider Object 


为 输入 框 或 文本 域 设 置 一 个 拼写 检查 provider . 


provider 必须 是 一 个 对 象 ， 它 有 一 个 spellcheck 方法 ， 这 个 方法 返回 扫 过 的 单词 是 否 拼写 
正确 . 


例子 ， 使 用 node-spellchecker 作为 一 个 provider: 


webFrame.setSpellCheckProvider("en-US", true, { 
spellCheck: function(text) { 
return !(require('spellchecker').isMisspelled(text)); 
} 
}); 


webFrame.registerURLSchemeAsSecure(scheme) 


e scheme String 
注册 scheme 为 一 个 安全 的 scheme. 


安全 的 schemes 不 会 引发 混合 内 容 warnings. 例 如 ，https 和 data 是 安全 的 schemes ， 
为 它们 不 能 被 活跃 网 络 攻 击 而 失效 . 


webFrame.registerURLSchemeAsBypassingCSP (scheme) 
e scheme String 

忽略 当前 网 页 内 容 的 安全 策略 ， 直 接 从 scheme 加载. 
webFrame.registerURLSchemeAsPrivileged(scheme) 


e scheme String 


通过 资源 的 内 容 安全 策略 ， 注 册 scheme 为 安全 的 scheme， 允许 注册 ServiceWorker# HX 
持 fetch API. 


webFrame. insertText(text) 


e text String 


向 获得 焦点 的 原色 插入 内 容 . 


webFrame.executeJavaScript(code[, userGesture] ) 


e code String 
e userGesture Boolean (可 选 ) - 默认 为 false. 


评估 页 面 代 码 . 


在 浏览 器 窗口 中 ， 一 些 HTMLAPIs ， 例 如 requestFullscreen ， 只 可 以 通过 用 户 手势 来 使 用 . 
设置 userGesture A true 可 以 突破 这 个 限制 . 


在 两 种 进程 中 都 可 用 的 模块 


clipboard 


Clipboard 模块 提供 方法 来 供 复制 和 粘 贴 操作 . 下面 例 子 展 示 了 如 何 将 一 个 字符 串 写 道 
clipboard 上 : 


const clipboard = require('electron').clipboard; 
clipboard.writeText('Example String'); 


E X Window 系统 上 , 有 一 个 可 选 的 clipboard. 你 可 以 为 每 个 方法 使 用 selection 来 控制 它 : 


clipboard.writeText('Example String', 'selection'); 
console.log(clipboard.readText('selection')); 


方法 

clipboard 模块 有 以 下 方法 : 

注意 : 测试 APls 已 经 标明 ， 并 且 在 将 来 会 被 删除 . 
clipboard.readText([type]) 
e type String (7 2) 

以 纯 文本 形式 从 clipboard 返回 内 容 . 
clipboard.writeText(text[, type]) 


e text String 
e type String (TÈ) 


以 纯 文 本 形式 向 clipboard 添加 内 容 . 
clipboard.readHtml([type]) 
e type String (7 2) 

返回 clipboard 中 的 标记 内 容 . 
clipboard.writeHtml(markup[, type]) 


e markup String 
e type String (可 选 ) 


向 clipboard 添加 markup A. 


clipboard. readImage( [type] ) 
。 type String (7 2) 

从 clipboard 中 返回 Nativelmage A È. 
clipboard.writeImage(image[, type] ) 


e image Nativelmage 
。 type String (7 2) 


向 clipboard 中 写 入 image . 
clipboard.readRtf([type] ) 
。 type String (TÈ) 

从 clipboard 中 返回 RTF 内 容 . 
clipboard .writeRtf(text[，type]) 


e text String 
。 type String (7 2) 


向 clipboard ? 5 A RTF 格式 的 text . 
clipboard.clear([type] ) 
e type String (TÈ) 

im © clipboard A X. 
clipboard.availableFormats([type] ) 
e type String (7 2) 


返回 clipboard 支持 的 格式 数组 . 


clipboard.has(data[, type]) Experimental 


e data String 
e type String (TÈ) 


返回 clipboard 是 否 支 持 指定 data 的 格式 . 


console.log(clipboard.has('<p>selection</p>')); 


clipboard.read(data[, type]) Experimental 


e data String 
e type String (可 选 ) 


读 取 clipboard 的 data . 


clipboard.write(data[, type] ) 


e data Object 

o text String 

o html String 

o image Nativelmage 
e type String (7 2) 


clipboard.write({text: 'test', html: "<b>test</b>"}); 


向 clipboard 5A data . 


crashReporter 


crash-reporter 模块 开局 发 送 应 用 崩溃 报告 . 


下 面 是 一 个 自动 提交 崩溃 报告 给 服务 器 的 例子 : 


const crashReporter = require('electron').crashReporter; 


crashReporter.start({ 
productName: 'YourName', 
companyName: 'YourCompany', 
submitURL: 'https://your-domain.com/url-to-submit', 
autoSubmit: true 


3); 
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e Socorro 


e mini-breakpad-server 


crash-reporter 模块 有 如 下 方法 : 


crashReporter.start(options) 


e options Object 

© companyName String 

© submituRL String - 崩溃 报告 发 送 的 路 径 ， 以 post 方 式 . 

© productName String (可 选 ) - 默认 为 Electron . 

o autoSubmit Boolean - 是 否 自动 提交 . 默认 为 true. 

© ignoreSystemCrashHandler Boolean - 默认 为 false. 
extra Object -一 个 你 可 以 定义 的 对 象 ， 附 带 在 崩溃 报告 上 一 起 发 送 . 只 有 字符 串 
属性 可 以 被 正确 发 送 ， 不 支持 诅 套 对 象 . 


o 


只 可 以 在 使 用 其 它 crashReporter APIs 之 前 使 用 这 个 方法 . 


注意 : 在 OS X, Electron 使 用 一 个 新 的 crashpad 客户 端 , 与 Windows 和 Linux 的 breakpad 
不 同 .为 了 开局 前 溃 点 搜集 ， 你 需要 在 主 进程 和 其 它 每 个 你 需要 搜集 前 溃 报 告 的 泻 染 进程 中 调 
用 crashReporter.start API 来 初始 化 crashpad . 


crashReporter.getLastCrashReport() 


返回 最 后 一 个 崩溃 报告 的 日 期 和 1D. 如 果 没 有 过 崩溃 报告 发 送 过 来 ， 或 者 还 没有 开始 崩溃 报告 
搜集 ， 将 返回 null. 


crashReporter.getUploadedReports() 


返回 所 有 上 载 的 前 溃 报 告 ， 每 个 报告 包含 了 上 载 日 期 和 ID. 


crash-reporter Payload 


谣 溃 报告 将 发 送 下 面 multipart/form-data POST 型 的 数据 给 submitURL : 


e ver String - Electron 版 本 . 

e platform String - 例如 'win32'. 

e process_type String - 例如 'renderer'. 

e guid String - 例如 '5e1286fc-da97-479e-91 8b-6bfb0c3d1c72' 

e version String- package.json 版 本 . 

@ _productName String - crashReporter options 对 象 中 的 产品 名 字 . 

e prod String - 基础 产品 名 字 . 这 种 情况 为 Electron. 

© _companyName String - crashReporter options 对 RP 的 公司 名 字 . 

e upload_file_minidump File - 前 演 报 告 按照 minidump 的 格式 . 

® crashReporter 中 的 extra 对 象 的 所 有 等 级 和 一 个 属性 . options object 


nativelmage 
在 Electron 中 , 对 所 有 创建 images 的 api 来 说 , 你 可 以 使 用 文件 路 径 或 nativeImage 实例 . 
如 果 使 用 null ， 将 创建 一 个 空 的 image tA. 


例如 , 当 创 建 一 个 tray 或 设置 窗口 的 图 标 时 候 ， 你 可 以 使 用 一 个 字符 串 的 图 片 路 径 : 


var appIcon = new Tray('/Users/somebody/images/icon.png'); 
var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'}); 


或 者 从 剪 切 板 中 读 取 图 片 ， 它 返回 的 是 nativeImage : 


var image = clipboard.readImage(); 
var appIcon = new Tray(image); 


支持 的 格式 


当前 支持 PN6 和 JPEG 图 片 格式 . 推荐 PN6 ， 因 为 它 支持 透明 和 无 损 压 缩 . 


在 Windows, 你 也 可 以 使 用 ico 图 标的 格式 . 


= 八 mR 

ma Pt AA 

如 果 平台 支持 high-DPI， 你 可 以 在 图 片 基础 路 径 后 面 添加 ox > TARREI HDRES 
图 片 . 


例如 ， 如 果 icon.png 是 一 个 普通 图 片 并 且 拥 有 标准 分 辨 座 ， 然 后 icon@2x.png 将 被 当 作 高 
分 辩 率 的 图 片 处 理 ， 它 将 拥有 双 倍 DPI 密度 . 


如 果 想 同时 支持 展示 不 同 分 辩 率 的 图 片 ， 你 可 以 将 拥有 不 同 Size 的 图 片 放 在 同一 个 文件 夹 
F> RA DPI 后 组 .例如 : 


images/ 

|— icon.png 
| icon@2x.png 
L— icon@3x.png 


var appIcon = new Tray('/Users/somebody/images/icon.png'); 


也 支持 下 面 这 些 DPI 后 级 : 


© @1x 


© @1.25x 
e @1.33x 
@ @1.4x 
@ @1.5x 


@ @1.8x 


© @2.5x 


片 由 黑色 和 清 色 (和 一 个 alpha 通道 ) 组 成 . 模板 图 片 不 是 单独 使 用 的 ， 而 是 通常 和 其 
内 容 混合 起 来 创建 期 望 的 最 终 效果 . 


见 的 用 力 是 将 模板 图 片 用 到 菜单 栏 图 片上 ， 所 以 它 可 以 同时 适应 亮 、 黑 不 同 的 菜单 栏 . 


z% 


最 
注意 : 模板 图 片 只 在 OS X 上 可 用 . 
为 了 将 图 片 标识 为 一 个 模板 图 片 ， 它 的 文件 名 应 当 以 Template 结尾 . 例如 : 


èe xxxTemplate.png 


@ xxxTemplate@2x.png 
方法 
nativeImage 类 有 如 下 方法 : 
nativeImage.createEmpty() 
创建 一 个 空 的 nativeImage 实例 . 


nativeImage.createFromPath(path) 

e path String 
从 指定 path 创建 一 个 新 的 nativeImage 实例 . 
nativeImage.createFromBuffer (buffer[, scaleFactor] ) 


e buffer Buffer 
e scaleFactor Double (* i) 


从 buffer 创建 一 个 新 的 nativeImage 实例 .默认 scaleFactor 是 1.0. 


nativeImage.createFromDataURL(dataURL) 
e dataurL String 


从 datauRL 创建 一 个 新 的 nativeImage 实例 . 


实例 方法 
nativeImage 有 如 下 方法 : 
const nativeImage = require('electron').nativeImage; 
var image = nativeImage.createFromPath('/Users/somebody/images/icon.png'); 
image. toPng() 
返回 一 个 Buffer ， 它 包含 了 图 片 的 PNG 编码 数据 . 
image.toJpeg(quality) 
e quality Integer (必须 )- Æ 0-100 Ž Ñ. 
返回 一 个 Buffer ， 它 包含 了 图 片 的 spec 编码 数据 . 
Image .toDataURL( ) 


返回 图 片 数据 的 URL. 


image.getNativeHandle() OSX 


返回 一 个 保存 了 c 指针 的 Buffer 来 潜在 处 理 原始 图 像 .在 OS X, 将 会 返回 一 个 NSImage 指针 
实例 . 


注意 那 返 回 的 指针 是 潜在 原始 图 像 的 弱 指 针 ， 而 不 是 一 个 复制 ， 你 必须 确保 与 nativeImage 
的 关联 不 间断 . 


image.isEmpty( ) 
返回 一 个 boolean ， 标 识 图片 是 否 为 空 . 


image.getSize() 


返回 图 片 的 Size. 


image .setTemplateImage(option) 
e option Boolean 
将 图 片 标识 为 模板 图 片 . 
image.isTemplateImage( ) 


返回 一 个 boolean ， 标 识 图 片 是 否 是 模板 图 片 . 


screen 


screen 模块 检索 屏幕 的 size’? ska? 和 鼠标 位 置 等 的 信息 .在 app 模块 的 ready 事件 触发 之 
前 不 可 使 用 这 个 模块 . 


screen 是 一 个 EventEmitter. 


注意 : 在 泻 染 进程 /开发 者 工具 栏 ，window,screen 是 一 个 预 设 值 的 DOM 属性 , 所 以 这 样 写 
var screen = require('electron').screen 将 不 会 工作 . 在 我 们 下 面 的 例子 , 我 们 取代 使 用 可 变 
名 字 的 electronscreen . 一 个 例子 ， 创 建 一 个 充满 丨 个 屏幕 的 窗口 : 


const electron = require('electron'); 
const app = electron.app; 
const BrowserWindow = electron.BrowserWindow; 


var mainwWindow; 


app.on('ready', function() { 
var electronScreen = electron.screen; 
var size = electronScreen.getPrimaryDisplay().workAreaSize; 
mainWindow = new BrowserWindow({ width: size.width, height: size.height }); 


3); 


另 一 个 例子 ， 在 次 页 外 创建 一 个 窗口 : 


const electron = require('electron'); 
const app = electron.app; 
const BrowserWindow = electron.BrowserwWindow; 


var mainWindow; 


app.on('ready', function() { 
var electronScreen = electron.screen; 
var displays = electronScreen.getAllDisplays(); 
var externalDisplay = null; 
for (var i in displays) { 
if (displays[i].bounds.x != © || displays[i].bounds.y != 0) { 
externalDisplay = displays[i]; 
break; 
} 
} 


if (externalDisplay) { 
mainWindow = new BrowserWindow( { 
x: externalDisplay.bounds.x + 50, 
y: externalDisplay.bounds.y + 50 


3); 
} 
3); 


Display 对 象 


Display 对 象 表示 了 物力 方式 连接 系统 . 一 个 伪造 的 Display 或 许 存 在 于 一 个 无 头 系统 中 
或 者 一 个 display 相当 于 一 个 远程 的 、 虚 拟 的 display. 


èe display object 
o id Integer- 4display 相关 的 唯一 性 标志 . 
o rotation Integer - 可 以 是 0, 1, 2, 3, 每 个 代表 了 屏幕 旋转 的 度数 0, 90, 180, 270. 
© scaleFactor Number - Output device's pixel scale factor. 
©  touchSupport String - 可 以 是 available , Unavailable , unknown . 
© bounds Object 
o size Object 
© workArea Object 
© workAreaSize Object 


事件 


Screen 模块 有 如 下 事件 : 


Event: display-added 
返回 : 


e event Event 


e newDisplay Object 


当 添 加 了 newDisplay 时 发 出 事件 


Event: display-removed 
返回 : 


e event Event 
e oldDisplay Object 


当 移 出 了 oldpisplay 时 发 出 事件 


Event: dispblay-metrics-changed 
返回 : 


e event Event 
e display Object 
e changedMetrics Array 


当 一 个 display 中 的 一 个 或 更 多 的 metrics 改变 时 发 出 事件 .changedMetrics 是 一 个 用 来 描 
述 这 个 改变 的 数组 .可 能 的 变化 为 bounds ， workArea , scaleFactor 和 rotation 

方法 

Screen 模块 有 如 下 方法 : 


screen.getCursorScreenPoint() 


返回 当前 鼠标 的 绝对 路 径 . 


screen.getPrimaryDisplay( ) 


返回 最 主要 的 display. 


screen.getAllDisplays() 


返回 一 个 当前 可 用 的 display 数组 . 


screen.getDisplayNearestPoint (point) 


e point Object 
o x Integer 
o y Integer 


返回 离 指定 点 最 近 的 display. 


screen.getDisplayMatching(rect) 


e rect Object 
o x Integer 
o y Integer 
o width Integer 
o height Integer 


返回 与 提供 的 边界 范围 最 密切 相关 的 display. 


shell 
shell 模块 提供 了 集成 其 他 桌面 客户 端的 关联 功能 . 
在 用 户 默认 浏览 器 中 打开 URL 的 示例 : 


var shell = require('shell'); 


shell.openExternal('https://github.com'); 


Methods 
shell Zk EBA ATF BA: 


shell.showItemInFolder (fullPath) 
e fullpath String 
打开 文件 所 在 文件 夹 ,一 般 情 况 下 还 会 选中 它 . 
shell.openItem(fullPath) 

e fullPath String 
以 默认 打开 方式 打开 文件 . 
shell.openExternal(ur1l) 


e url String 


以 系统 默认 设置 打开 外 部 协议 .( 例 如 ,mailto: somebody@somewhere.io 会 打开 用 户 默 认 的 邮 
件 客户 端 ) 


shell.moveItemToTrash(fullPath) 


e fullpath String 


删除 指定 路 径 文件 ,并 返回 此 操作 的 状态 值 (boolean 类 型 )， 


shell. beep() 


播放 beep 声音 . 


开发 


编码 规范 


以 下 是 Electron 项 目的 编码 规范 。 


C++ 和 Python 

对 于 C++ 和 Python， 我们 遵循 Chromium 的 编码 规范 。 你 可 以 使 用 script/cpplint.py 来 
检验 文件 是 否 符合 要 求 。 

我 们 目前 使 用 的 Pyhton 版 本 是 Python 2.7。 


C++ 代码 中 用 到 了 许多 Chromium 中 的 接口 和 数据 类 型 ， 所 以 布 望 你 能 熟悉 它们 。 
Chromium 中 的 重要 接口 和 数据 结构 就 是 一 篇 不 错 的 入 门 文档 ， 里 面 提 到 了 一 些 特殊 类 型 、 域 
内 类 型 (退出 作用 域 时 自动 释放 内 存 ) 、 日 志 机 制 ， 等 等 。 


CoffeeScript 


对 于 CoffeeScript， 我 们 遵循 GitHub 的 编码 规范 及 以 下 规则 : 


© 文件 不 要 以 换行 符 结尾 ， 我 们 要 遵循 Google 的 编码 规范 。 

e 文件 名 使 用 - 而 不 是 _ 来 连接 单词 ， 比 如 file-name.coffee 而 不 是 
file_name.coffee ， 这 是 沿用 github/atom 模块 的 命名 方式 ( module-name ) 。 这 条 规则 
仅 适 用 于 .coffee 文件 。 


API 命名 


当 新 建 一 个 API 时 ， 我 们 倾向 于 使 用 getters 和 setters 而 不 是 jQuery 单 函数 的 命名 方式 ， 比 
如 .getText() 和 .setText(text) 而 不 是 .text([text]) 。 这 里 有 关于 该 规则 的 讨论 记录 。 


源码 目录 结构 


Electron 的 源 代 码 主 要 依据 Chromium 的 拆 分 约定 被 拆 成 了 许多 部 分 。 


为 了 更 好 地 理解 源 代 码 ， 您 可 能 需要 了 解 一 下 Chromium 的 多 进程 架构 。 


源 代 码 的 结构 


Electron 
| 一 atom - Electron 的 源 代码 


PUR SSS RSS SeR a SRA eee 


|— app - 系统 入 口 代码 

| 一 browser - 包含 了 主 窗 口 、UI 和 其 他 所 有 与 主 进程 有 关 的 东西 ， 它 会 告诉 泻 染 进 程 如 何 管 理 页 面 

| 一 lib - 主 进程 初始 化 代码 中 JavaScript 部 分 的 代码 

| 一 ui - 不 同 平台 上 UL 部 分 的 实现 

| cocoa - Cocoa 部 分 的 源 代码 

| | 一 gtk - GTK+ 部 分 的 源 代码 

| L— win - Windows GUI 部 分 的 源 代码 

| 一 default_app - 在 没有 指定 app 的 情况 下 Electron 启动 时 默认 显示 的 页 面 

| 一 api - 主 进程 API 的 实现 

| L— lib - API 实现 中 Javascript 部 分 的 代码 

| net - 网 络 相关 的 代码 

一 mac - 与 Mac 有 关 的 Objective-C 代码 

L— resources - 图 标 ， 平 台 相 关 的 文件 等 

renderer - 运行 在 泻 染 进程 中 的 代码 

| 一 lib - 泻 染 进 程 初 始 化 代码 中 JavaScript 部 分 的 代码 

[一 api - 泻 染 进程 API 的 实现 
L— lib - API 实现 中 Javascript 部 分 的 代码 

common - 同时 被 主 进程 和 泻 染 进程 用 到 的 代码 ， 包 括 了 一 些 用 来 将 node 的 事件 循环 

| 整合 到 Chromium 的 事件 循环 中 时 用 到 的 工具 函数 和 代码 

| lib - 同时 被 主 进程 和 泻 染 进 程 使 用 到 的 Javascript 初始 化 代码 

L— api - 同时 被 主 进程 和 浑 染 进程 使 用 到 的 API 的 实现 以 及 Electron 内 置 模块 的 基础 设施 
L— lib - API 实现 中 Javascript 部 分 的 代码 

chromium_src - 从 Chromium 项 目 中 拷贝 来 的 代码 

docs - 英语 版 本 的 文档 

docs-translations - 各 种 语言 版 本 的 文档 翻译 

spec - 自动 化 测试 

atom.gyp - Electron 的 构建 规则 

common.gypi - 为 诸如 “node” 和 “breakpad” 等 其 他 组 件 准备 的 编译 设置 和 构建 规则 


DO 


他 目录 的 结构 


script - 用 于 诸如 构建 、 打 包 、 测 试 等 开发 用 途 的 脚本 

tools - 在 gyp 文件 中 用 到 的 工具 脚本 ， 但 与 script 目录 不 同 ， 该 目录 中 的 脚本 不 应 该 
被 用 户 直 接 调 用 

vendor - 第 三 方 依赖 项 的 源 代码 ， 为 了 防止 人 们 将 它 与 Chromium 源码 中 的 同名 目录 相 
混淆 ， 在 这 里 我 们 不 使 用 third_party 作为 目录 名 

node_modules - 在 构建 中 用 到 的 第 三 方 node 模块 

out - ninja 的 临时 输出 目录 

dist- 由 脚本 script/create-dist,py 创建 的 临时 发 布 目录 

external_binaries - 下 载 的 不 支持 通过 gyp 构建 的 预 编译 第 三 方 框架 


Electron 和 NW.js (原名 node-webkit) 在 技术 上 
的 差异 


备注 : Electron 的 原名 是 Atom Shell 。 


与 NW.js 相似 ，Electron 提供 了 一 个 能 通过 JavaScript 和 HTML 创建 桌面 应 用 的 平台 ， 同 时 
集成 Node 来 授予 网 页 访问 底层 系统 的 权限 。 


但 是 这 两 个 项 目 也 有 本 质 上 的 区 别 ， 使 得 Electron 和 NW.js 成 为 两 个 相互 独立 的 产品 。 
1. 应 用 的 入 口 


在 NW.js 中 ， 一 个 应 用 的 主 入 口 是 一 个 页 面 。 你 在 package.json 中 指定 一 个 主页 面 ， 它 会 
作为 应 用 的 主 窗口 被 打开 。 


在 Electron 中 ， 入 口 是 一 个 JavaScript 脚本 。 不 同 于 直接 提供 一 个 URL， 你 需要 手动 创建 一 
个 浏览 器 窗口 ， 然 后 通过 API 加 载 HTML 文件 。 你 还 可 以 监听 窗口 事件 ， 决 定 何 时 让 应 用 退 
出 o 


Electron 的 工作 方式 更 像 Node.js 运行 时 。 Electron 的 APIs 更 加 底层 ， 因 此 你 可 以 用 它 替 代 
PhantomJS 做 浏览 器 测试 。 


2. 构建 系统 


为 了 避免 构建 整个 Chromium 带 来 的 复杂 度 ，Electron 通过 libchromiumcontent 来 访问 
Chromium 的 Content API © libchromiumcontent 是 一 个 独立 的 、 引 入 了 Chromium Content 
模块 及 其 所 有 依赖 的 共享 库 。 用 户 不 需要 一 个 强劲 的 机 器 来 构建 Electron 。 


3. Node 集成 


在 NW.js， 网 页 中 的 Node 集成 需要 通过 给 Chromium 打 补 丁 来 实现 。 但 在 Electron 中 ， 我 
们 选择 了 另 一 种 方式 : 通过 各 个 平台 的 消息 循环 与 libuv 的 循环 集成 ， 避 免 了 直接 在 
Chromium 上 做 改动 。 你 可 以 看 node bindings 来 了 解 这 是 如 何 完成 的 。 


4. 多 上 下 文 


如 果 你 是 有 经 验 的 NW.js 用 户 ， 你 应 该 会 熟悉 Node 上 下 文 和 web 上 下 文 的 概念 。 这 些 概念 
的 产生 源 于 NW.js 的 实现 方式 。 


通过 使 用 Node 的 乡 上 下 文 特性 ，Electron 不 需要 在 网 页 中 引入 新 的 JavaScript HFX ° 


Build System Overview 


Electron 使 用 gyp 来 生成 项 目 ， 使 用 ninja 来 构建 项 目 . 项 目 配置 可 以 在 .gyp 和 .gypi X 
件 中 找到 . 


Gyp 文件 
下 面 的 gyp 文件 包含 了 构建 Electron 的 主要 规则 : 


e atom.gyp 定义 了 Electron 它 自 己 是 怎样 被 构建 的 . 

© common.gypi 调整 node 的 构建 配置 ， 来 让 它 结合 Chromium 一 起 构建 . 

@ vendor/brightray/brightray.gyp 定义 了 brightray 是 如 何 被 构建 的 并 且 包含 了 默认 
配置 来 连接 到 Chromium. 

èe vendor/brightray/brightray.gypi 包含 了 常用 的 创建 配置 . 


创建 组 件 


在 Chromium 还 是 一 个 相当 大 的 项 目的 时 候 ， 最 后 链接 阶段 会 花 了 好 几 分 钟 ， 这 让 开发 变 得 
很 困难 . 为 了 解决 这 个 困难 ，Chromium 引入 了 "component build" ， 这 让 每 个 创建 的 组 建 都 
是 分 隔 开 的 共享 库 ， 让 链接 更 快 ， 但 是 这 浪费 了 文件 大 小 和 性 能 . 


在 Electron 中 ， 我 们 采用 了 一 个 非常 相似 的 方法 : 在 创建 debug ,二 进 制 文件 会 被 链接 进入 
一 个 Chromium 组 件 的 共享 版 本 库 来 达到 快速 链接 ; 在 创建 Release ,二进制 文件 会 被 链接 进 
入 一 个 静态 版 本 库 , 所 以 我 们 可 以 有 最 小 的 二 进 制 文件 size 和 最 佳 的 体验 . 


Minimal Bootstrapping 


在 运行 bootstrap 脚本 的 时 候 ， 所 有 的 Chromium 预 编译 二 进 制 文件 会 被 下 载 .默认 静态 库 和 
共享 库 会 被 下 载 ， 并 且 项 目的 最 后 大 小 会 在 800MB 到 2GB 之 间 ， 这 取决 于 平台 类 型 . 


默认 ，1ibchromiumcontent 是 从 Amazon Web Services 上 下 载 下 来 的 .如 果 设 置 了 
LIBCHROMIUMCONTENT_MIRROR 环境 变量 ，bootstrap 脚 本 会 从 这 里 下 载 下 来 . 

libchromiumcontent -qiniu-mirror 是 libchromiumcontent 的 映射 .如 果 你 不 能 连接 AWS? 你 
可 以 切换 下 载 路 

径 : export LIBCHROMIUMCONTENT_MIRROR=http://7xk3d2.d11.z0.g1b.clouddn.com/ 如 果 只 是 想 快 
速 搭建 一 个 Electron 的 测试 或 开发 环境 ， 可 以 通过 --dev 参数 只 下 载 共享 版 本 库 : 


$ ./script/bootstrap.py --dev 
$ ./script/build.py -c D 


Two-Phase Project Generation 


在 Release 和 debug 构建 的 时 候 后 ，Electron 链接 了 不 同 配置 的 库 .然而 gyp 不 支持 为 不 
同 的 配置 文件 进行 不 同 的 链接 设置 . 


为 了 规避 这 个 问题 ，Electron 在 运行 gyp 的 时 候 ， 使 用 了 一 个 gyp 的 变量 
libchromiumcontent_component 来 控制 应 该 使 用 哪个 链接 设置 ， 并 且 只 生成 一 个 目标 . 


Target Names 


与 大 多 数 的 项 目 不 同 ， 它 们 使 用 Release 和 debug 作为 目标 名 字 ， 而 Electron 使 用 使 用 的 
是 R 和 p. 这 是 因为 如 果 只 定义 了 一 个 Release 或 debug 构建 配置 ， gyp 会 随机 崩溃 ， 
并 且 在 同一 时 候 ，Electron 只 生成 一 个 目标 ， 如 上 所 述 . 


这 只 对 开发 者 可 用 ， 如 果 想 重新 构建 Electron ， 将 不 会 成 功 . 


Build Instructions (OS X) 


遵循 下 面 的 引导 ， 在 OS X 上 构建 Electron . 


前 提 
e OSX >= 10.8 
e Xcode >= 5.1 


e node.js (外 部 ) 
如 果 你 通过 Homebrew 使 用 Python 下 载 ， 需 要 安装 下 面 的 Python 模块 : 


e pyobjc 
获取 代码 


$ git clone https://github.com/electron/electron.git 


Bootstrapping 


bootstrap 脚本 也 是 必要 下 载 的 构建 依赖 ， 来 创建 项 目 文 件 .注意 我 们 使 用 的 是 ninja 来 构建 
Electron， 所 以 没有 生成 Xcode 项 目 . 


$ cd electron 
$ ./script/bootstrap.py -v 


构建 
创建 Release 、 pebug target: 


$ ./script/build.py 


可 以 只 创建 debug target: 


$ ./script/build.py -c D 


创建 完毕 , 可 以 在 out/D 下 面 找到 Electron.app . 


32 位 支持 
在 OS X 上 ， 构 建 Electron 只 支持 64 位 的 ， 不 支持 32 位 的 | 
M| ax, 

测试 你 的 修改 是 否 符 合 项 目 代码 风格 ， 使 用 : 


$ ./script/cpplint.py 


测试 有 效 性 使 用 : 


$ ./script/test.py 


Build Instructions (Windows) 


遵循 下 面 的 引导 ， 在 Windows £74 # Electron . 


前 提 


e Windows 7 / Server 2008 R2 or higher 

e Visual Studio 2013 with Update 4 - download VS 2013 Community Edition for free. 
e Python 2.7 

e Node.js 

e Git 


如 果 你 现在 还 没有 安装 Windows , modern.ie 有 一 个 timebombed 版 本 的 Windows ， 你 可 以 
用 它 来 构建 Electron. 


构建 Electron 完全 的 依赖 于 命令 行 ， 并 且 不 可 通过 Visual Studio. 可 以 使 用 任何 的 编辑 器 来 开 
发 Electron ， 未 来 会 支持 Visual Studio. 


注意 : 虽然 Visual Studio 不 是 用 来 构建 的 ， 但 是 它 仍然 必须 的 ， 因 为 我 们 需要 它 提供 的 构建 
工具 栏 . 


注意 : Visual Studio 2015 不 可 用 . 请 确定 使 用 MSVS 2013. 
+ a 
获取 代码 


$ git clone https://github.com/electron/electron.git 


Bootstrapping 


bootstrap 脚本 也 是 必要 下 载 的 构建 依赖 ， 来 创建 项 目 文件 .注意 我 们 使 用 的 是 ninja 来 构建 
Electron， 所 以 没有 生成 Visual Studio 项 目 . 


$ cd electron 
$ python script\bootstrap.py -v 


构建 


创建 Release 、 pebug target: 


$ python script\build.py 


可 以 只 创建 debug target: 


$ python script\build.py -c D 


创建 完毕 , 可 以 在 out/p (debug target) 或 out\R (release target) 下 面 找到 electron.exe . 


64bit Build 
为 了 构建 64 位 的 target, 在 运行 bootstrap 脚本 的 时 候 需 要 使 用 --target_arch=x64 : 


$ python script\bootstrap.py -v --target_arch=x64 


其 他 构建 步骤 完全 相同 . 


Tests 

测试 你 的 修改 是 否 符合 项 目 代 码 风 格 ， 使 用 : 
$ python script\cpplint.py 

测试 有 效 性 使 用 : 


$ python script\test.py 


在 构建 debug 时 为 Tests 包 含 原 生 模 块 (例如 runas ) 将 不 会 执行 (详情 #2558), 但 是 它们 在 构 
建 release 会 起 效 . 


运行 release 构建 使 用 : 


$ python script\test.py -R 


解决 问题 


Command xxxx not found 


如 果 你 遇 到 了 一 个 错误 ， 类 似 command xxxx not found 可 以 尝试 使 用 
VS2012 Command Prompt 控制 台 来 执行 构建 脚本 . 


Fatal internal compiler error: C1001 


确保 你 已 经 安装 了 Visual Studio 的 最 新 安装 包 . 


Assertion failed: ((handle))->activecnt >= 0 
如 果 在 Cygwin 下 构建 的 ， 你 可 能 会 看 到 bootstrap.py 失败 并 且 附 带 下 面 错 误 : 


Assertion failed: ((handle))->activecnt >= 0, file src\win\pipe.c, line 1430 


Traceback (most recent call last): 
File "script/bootstrap.py", line 87, in <module> 
sys.exit(main()) 
File "script/bootstrap.py", line 22, in main 
update_node_modules('.') 
File "script/bootstrap.py", line 56, in update_node_modules 
execute([NPM, '‘install']) 
File "/home/zcbenz/codes/raven/script/lib/util.py", line 118, in execute 
raise e 
subprocess.CalledProcessError: Command '['npm.cmd', 'install']' returned non-zero exit st 


了 __# 


这 是 由 同时 使 用 Cygwin Python 和 Win32 Node 造成 的 bug. 解 决 办 法 就 是 使 用 Win32 
Python 执行 bootstrap 脚本 (假定 你 已 经 在 目录 c:\python27 下 安装 了 Python): 





$ /cygdrive/c/Python27/python.exe script/bootstrap.py 


LNK1181: cannot open input file 'kernel32.lib' 


重新 安装 32 位 的 Node js. 


Error: ENOENT, stat 
"C:\Users\USERNAME\AppData\Roaming\npm' 
简单 创建 目录 应 该 可 以 解决 问题 : 


$ mkdir ~\AppData\Roaming\npm 


node-gyp is not recognized as an internal or external 
command 


如 果 你 使 用 Git Bash 来 构建 ， 或 许 会 遇 到 这 个 错误 ， 可 以 使 用 PowerShell 或 VS2012 
Command Prompt 来 代替 . 


Build Instructions (Linux) 


遵循 下 面 的 引导 ， 在 Linux 上 构建 Electron . 


Prerequisites 


e Python 2.7.x. 一 些 发 行 版 如 CentOS 仍然 使 用 Python 2.6.x ， 所 以 或 许 需要 check 你 的 
Python 版 本 ， 使 用 python -v . 

e Node.js v0.12.x. 有 很 多 方法 来 安装 Node. 可 以 从 Node.js 下 载 原文 件 并 且 编 译 它 .也 可 以 
作为 一 个 标准 的 用 户 在 home 目录 下 安装 node .或 者 尝试 使 用 仓库 NodeSource. 

。 Clang 3.4 或 更 新 的 版 本 . 

© GTK+ 开 发 头 文件 和 libnotify. 


在 Ubuntu, 安装 下 面 的 库 : 


$ sudo apt-get install build-essential clang libdbus-1-dev libgtk2.0-dev \ 
libnotify-dev libgnome-keyring-dev libgconf2-dev \ 
libasound2-dev libcap-dev libcups2-dev libxtst-dev \ 
libxss1 libnss3-dev gcc-multilib g++-multilib 


在 Fedora, 安装 下 面 的 库 : 


$ sudo yum install clang dbus-devel gtk2-devel libnotify-devel libgnome-keyring-devel \ 
xorg-x11-server-utils libcap-devel cups-devel libXtst-devel \ 
alsa-lib-devel libXrandr-devel GConf2-devel nss-devel 


E 


其 它 版 本 的 也 许 提供 了 相似 的 包 来 安装 ， 通 
件 的 . 


包 管理 器 ， 例 如 pacman. 或 一 个 可 以 编译 源 文 


位 


使 用 虚拟 机 


如 果 在 虚拟 机 上 构建 Electron， 你 需要 一 个 固定 大 小 的 设备 ， 至少 需要 25 gigabytes . 
+ x 
获取 代码 


$ git clone https://github.com/electron/electron.git 


Bootstrapping 


bootstrap 脚本 也 是 必要 下 载 的 构建 依赖 ， 来 创建 项 目 文 件 .需要 使 用 Python 2.7.x 来 让 脚本 成 
功 执行 .正确 下 载 文 件 会 花费 较 长 的 时 间 . 注意 我 们 使 用 的 是 ninja 来 构建 Electron， 所 以 没 
有 生成 Makefile 项 目 . 


$ cd electron 
$ ./script/bootstrap.py -V 


交叉 编译 
如 果 想 创建 一 个 arm target ， 应 当 还 要 下 载 下 面 的 依赖 : 


$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \ 
g++-arm- linux -gnueabihf 


为 了 编译 arm 或 ia32 targets, 你 应 当 为 bootstrap.py 脚本 使 用 --target_arch #2: 


$ ./script/bootstrap.py -v --target_arch=arm 


构建 


创建 Release 、 pebug target: 


$ ./script/build.py 


这 个 脚本 也 许 会 在 目录 out/R 下 创建 一 个 巨大 的 可 执行 的 Electron . 文件 大 小 或 许 会 超过 
1.3 gigabytes. 原因 是 Release target 二 进 制 文件 包含 了 调试 符号 .运行 create-dist.py 脚 
本 来 减 小 文件 的 size : 


$ ./script/create-dist.py 


这 会 在 dist 目录 下 创建 一 个 有 大 量 小 文件 的 工作 空间 . 运行 create-dist.py 脚本 之 后 , 或 许 你 
有 删除 仍然 在 out/R 下 的 1.3+ gigabyte 三 进 制 文 件 . 


a 


a) 


可 以 只 创建 Debug target: 


$ ./script/build.py -c D 


创建 完毕 ， 可 以 在 out/D 下 面 找到 electron . 


Cleaning 


删除 构建 文件 : 


$ ./script/clean.py 


解决 问题 
确保 你 已 经 安装 了 所 有 的 依赖 . 
Error While Loading Shared Libraries: libtinfo.so.5 


预 构建 的 clang 会 尝试 链接 到 libtinfo.so.5 . 取决 于 host 架构 , 适当 的 使 用 libncurses : 


$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5 


Tests 

测试 你 的 修改 是 否 符合 项 目 代 码 风 格 ， 使 用 : 
$ ./script/cpplint.py 

测试 有 效 性 使 用 : 


$ ./script/test.py 


Setting Up Symbol Server in Debugger 


调试 symbols 让 你 有 更 好 的 调试 sessions. 它们 有 可 执行 的 动态 库 的 函数 信息 ， 并 且 提 供 信 
息 来 获得 洁净 的 呼叫 栈 . 一 个 Symbol 服务 器 允许 调试 器 自动 加 载 正确 的 symbols, 二 进 制 文 
件 和 资源 文件 ， 不 用 再 去 强制 用 户 下 载 巨大 的 调试 文件 . 服务 器 函数 类 似 Microsoft's symbol 
server ， 所 以 这 里 的 记录 可 用 . 

注意 ， 因 为 公众 版 本 的 Electron 构建 是 最 优化 的 ， 调 试 不 一 定 一 直 简 单 .调试 器 将 不 会 给 显示 
出 所 有 变量 内 容 ， 并 且 因 为 内 联 ， 尾 调用 ， 和 其 它 编译 器 优化 ， 执 行路 径 会 看 起 来 很 怪异 . 唯 
一 的 解决 办 法 是 搭建 一 个 不 优化 的 本 地 构建 . 

Electron 使 用 的 官方 symbol 服务 器 地 址 为 http://54.249.141.255:8086/atom-shell/symbols . 
你 不 能 直接 访问 这 个 路 径 ， 必 须 将 其 添加 到 你 的 调试 工具 的 symbol 路 径 上 .在 下 面 的 例子 

中 ， 使 用 了 一 个 本 地 缓存 目录 来 避免 重复 从 服务 器 获取 PDB. 在 你 的 电脑 上 使 用 一 个 恰当 的 组 
存 目 录 来 代替 c:\code\symbols . 


Using the Symbol Server in Windbg 

Windbg symbol 路 径 被 配制 为 一 个 限制 带 星 号 字符 的 字符 串 . 要 只 使 用 Electron $ symbol 服 
务 器 , 将 下 列 记录 添加 到 你 的 symbol 路 径 (注意 : 如 果 你 愿意 使 用 一 个 不 同 的 地 点 来 下 载 
symbols， 你 可 以 在 你 的 电脑 中 使 用 任何 可 写 的 目录 来 代替 c:\code\symbols ): 


SRV*c:\code\symbols\*http://54.249.141.255:8086/atom-shell/symbols 


使 用 Windbg 菜单 或 通过 输入 .sympath 命令 ， 在 环境 中 设置 一 个 _NT_SYMBOL_PATH 字符 串 . 
如 果 你 也 想 从 微软 的 symbol 服务 器 获得 symbols ， 你 应 当 首 先 将 它们 先 列 出 来 : 


SRV*c:\code\symbols\*http://msdl.microsoft .com/download/symbols;SRV*c:\code\symbols\*http 


4 aay 





在 Visual Studio 中 使 用 symbol 服务 器 
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Window “Community 
‘Sh Attach to Process... Ctrl+Alt+P 


% Connect to Database... 
E Code Snippets Manager... Ctrl+K, Ctrl+B 








Choose Toolbox Items... 

Error Lookup 

ILDasm 

Visual Studio 2005 Command Prompt 
External Tools... 

Import and Export Settings... 


Customize... 





Options 








Environment Symbols 
Projects and Solutions Using symbol files from an unknown or untrusted location can be 
Source Control harmful to your computer. 

Text Editor 


Database Tools Symbol file ¢,pdb) locations: 国 [xjlsjLs] 


加 -Debugging 回 http: //symbols. mozilla. org/firefox 


General 
v i „mi i 
E iE http: //msdl. microsoft. com/download/symbals 


Just-In-Time 
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+). Device Tools Cache symbols from symbol servers to this directory: 
+ ata Designer Í C:\mozilla\symbols 
=- Microsoft Office Keyboard Settings — = j = 


+) Windows Forms Designer [C] Search the above locations only when symbols are loaded manually 




















Load symbols using the updated settings when this dialog is closed 











Troubleshooting: Symbols will not load 
在 Windbg 中 输入 下 列 命令 ， 打 印 出 未 什么 symbols 没有 加 载 : 


> !Sym noisy 
> .reload /f chromiumcontent.d1l 


在 调试 中 使 用 Symbol Server 214 


